This page is about the most basic facts you need to know to get up and running with the previous stable release of VM, version 7.19. There is a quick-start guide for the current version of VM at ViewMailQuickStart.



First, make a directory to store your email folders. ~/email would not be a bad choice.


Configuration entails setting variables that tell VM where to get your mail and where to put your mail, among other things. Broadly speaking, you can either write your VM configuration in .vm or .emacs. Which you choose depends on how you prefer to organize your emacs startup script. Let us consider the relative merits of each way.

vm-init-file defaults to ~/.vm

This file is loaded the first time you run VM in an Emacs session.

By default, “L” is bound to vm-load-init-file. This is convenient when you make changes to .vm.

Maybe you want your VM settings grouped with other email-related settings in your .emacs, or in a separate script loaded by .emacs. A lot of people like to keep private information in a script separate from their .emacs.

For tidiness, you should set vm-init-file to nil.

    (setq vm-init-file nil)

Most Important Variables


The mailbox visited by VM at startup.

For example:

    (setq vm-primary-inbox "~/email/inbox.mbox")


VM transfers mail from the spool to the primary inbox via a temporary file called the crash box. This variable names the crash box file.

For example:

    (setq vm-crash-box "~/email/inbox.crash.mbox")


When you start VM, it will check for incoming mail in the spools listed in vm-spool-files. This list can be defined in simple form or complete form. Forget about simple form. Complete form is easy, and if you ever need to add another spool, you can just copy and modify what you have already written.

In complete form, each element of vm-spool-files is a list of three strings: (INBOX-PATH SPOOL CRASH-BOX-PATH)

You should have already set vm-primary-inbox and vm-crash-box so we have only to define SPOOL.

    (setq vm-spool-files `((,vm-primary-inbox

VM can download mail via pop.

    (setq vm-spool-files `((,vm-primary-inbox

See ViewMailAndPop for more details.

If your spool is an IMAP server, set vm-spool-files like this:

    (setq vm-spool-files `((,vm-primary-inbox

See ViewMailAndImap for more details.

Adding Spools

To add another spool apart from the primary, simply add another (INBOX-PATH SPOOL CRASH-BOX-PATH) form to the vm-spool-files list. Multiple spools may go into the same inbox. Spools that go to different inboxes should use different crash-boxes.

Other Basic Setup


If you do not use a package manager to install VM--that is, if your installation procedure is to simply put VM somewhere in your load-path--you should set up autoloads in your .emacs to let Emacs load VM when needed.

    (autoload 'vm "vm" nil t)
    (autoload 'vm-mode "vm" nil t)

Another convenience is to put vm-mode in your auto-mode-alist for mailbox files.

    (add-to-list 'auto-mode-alist '("\\.mbox$" . vm-mode))

External Utilities

VM comes with utilities to encode and decode base64 and quoted printable encoding. Although VM can also do these tasks internally, the external utilities are much faster. You won’t regret taking a couple of minutes to set them up.

At a shell prompt in your vm source directory, do:

    make utils

The binaries you just made are called qp-decode, qp-encode, base64-decode, and base64-encode. You do not need to install these binaries to a system directory, but you can if you like. Now in your VM configuration, set the following variables.

    (setq vm-mime-qp-decoder-program "/path/to/qp-decode"
          vm-mime-qp-encoder-program "/path/to/qp-encode"
          vm-mime-base64-decoder-program "/path/to/base64-decode"
          vm-mime-base64-encoder-program "/path/to/base64-encode"
          vm-mime-qp-decoder-switches nil
          vm-mime-qp-encoder-switches nil
          vm-mime-base64-decoder-switches nil
          vm-mime-base64-encoder-switches nil)

Both GNU Emacs and XEmacs have fast internal base64 encoding and decoding. If these functions are present in your emacs, they will be used instead of the external programs. Might as well set up the external programs anyway and you won’t have to think about it.