This guide contains practical advice and the most basic facts you need to know to get up and running with VM.

These instructions are about VM 8. Instructions for VM 7.19 can still be found at ViewMailSevenQuickStart.



Get VM from, and build it as per the instructions in the file INSTALL. It is not necessary to `make install’. You can eliminate a step from installation by running it from the build directory. You should, however, install the binary mime encoders and decoders. VM also has encode and decode functions written in elisp, but these programs are much faster. Both GNU Emacs and XEmacs now also have fast internal encoders and decoders, and those will be used instead of these programs, if they are present. Better to install them anyway and forget about it.

  # after you have done a successful `make' in the top level directory...
  cd src
  make install

Your .emacs now needs something like this:

  (add-to-list 'load-path "/path/to/vm/lisp")
  (require 'vm-autoloads)


Make a directory to store your email folders. ~/email would not be a bad choice.


We configure VM by setting variables that tell it 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 session. Let us consider the relative merits of each way.

Writing the configuration in vm-init-file (~.vm)
vm-init-file defaults to ~/.vm. This file is loaded the first time you run VM in an Emacs session. It is loaded even if you start emacs with the -q option. In vm-mode, “L” is bound to vm-load-init-file, so you have a convenient way to load .vm when you make changes to it.
Writing the configuration in ~/.emacs
Maybe you want your VM settings grouped with other email-related settings in your .emacs, or in a separate script loaded from it. 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.

VM has very many configuration options (“preferences”) and it is useful to have a way of blocking them for trouble shooting purposes. To use this facility, place the preferences in a separate vm-preferences file (~/.vm.preferences). The standard configuration options should still go in ~/.vm or ~/.emacs file, which include:

All other settings for VM variables should go in the ~/.vm.preferences file.

Local folders or Server folders?

An early decision you need to make is whether you will store your email on the local file system or keep it on mail servers (POP or IMAP). POP allows a single folder called ‘INBOX’ to be kept on the server but IMAP allows any number of folders in addition to ‘INBOX’. The advantage of keeping email on the servers is that you can read it and update it from multiple locations. VM allows you to keep your email on the mail servers (but cached locally for speed and convenience) or to download it to local folders.

The most common use of POP servers is to download mail to local folders. The best use of IMAP servers to use server folders.

Most Important Variables - Local folders


The mailbox visited by VM at startup. The default is `~/INBOX’ if that file exists, otherwise `~/Mail/inbox’. But don’t worry about that craziness. Just choose a file that is not a default for any mail client you use. It will be one small measure of protection if you need to debug, hack, or run multiple clients at once.

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.

Most Important Variables - POP Server Folders


If you receive your main incoming mail via a POP server, use:

    (setq vm-primary-inbox "pop:HOST:PORT:AUTH:USER:PASSWORD")

See ViewMailAndPop for more details.

Additional POP mail boxes

If you would like to visit additional POP mail boxes on other servers, define them in ‘vm-pop-folder-alist’. For example,

     (setq vm-pop-folder-alist
              ("*" "Yahoo! mail")
              ("pop:localhost:110:pass:someuser:*" "local mail")

The first string in each of the inner lists is a POP mailbox specification in the format “pop:HOST:PORT:AUTH:USER:PASSWORD”, and the second string is a short name.

You can visit the folders defined here using ‘M-x vm-visit-pop-folder’.

Most Important Variables - IMAP Server Folders


If you receive your main incoming mail via an IMAP server, use:

    (setq vm-primary-inbox "imap:HOST:PORT:Inbox:AUTH:USER:PASSWORD")

See ViewMailAndImap for more details.


All your IMAP accounts should be defined in the variable ‘vm-imap-account-alist’. For example,

     (setq vm-imap-account-alist
             ("*:login:becky:*" "becky")
             ("*:login:becky:*" "crickle")

The first string in each of the inner lists is an IMAP mailbox specification in the format “imap:HOST:PORT:*:AUTH:USER:PASSWORD”, and the second string is a short name.

You can visit folders on the declared IMAP accounts using ‘M-x vm-visit-imap-folder’. When prompted for the folder name, input it in the format ACCOUNT:MAILBOX. Here, ACCOUNT is the short name declared in the alist, e.g., ‘becky’. MAILBOX is the name of a folder on the IMAP server. File name completion is available for typing the ACCOUNT as well as the MAILBOX name.

Other Basic Setup


Here are some tips to better integrate VM in Emacs. These things should go in your .emacs, since if they are in your .vm, they would not be loaded until you run VM, which almost defeats the point.

Make vm-mode load for files with the extension `.mbox’.

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

Make ‘M-x compose-mail’ (also ‘C-x m’) create a VM-style composition buffer.

    (setq mail-user-agent 'vm-user-agent)