1 Starting Up

The first time VM is started in an Emacs session, it attempts to load the file specified by the variable vm-init-file, normally ~/.vm. If present this file should contain Lisp code, much like the .emacs file. It should contain the “configuration settings” for VM, i.e., variables that define where the mail folders are stored, where the incoming mail is to be found, the various directories that VM needs to use for its operation and the external applications that VM can invoke. You can reload this file by typing M-x vm-load-init-file from within VM.

In addition, VM also attempts to load a file specified by the variable vm-preferences-file, normally ~/.vm.preferences. This file should contain your preferential settings for various VM variables affecting how VM works. Since VM has well over one hundred configuration variables, use of the ~/.vm.preferences can considerably reduce clutter in the .vm file.

Invoking vm-load-init-file with a prefix argument (e.g., C-u) causes the vm-init-file to be loaded without the vm-preferences-file. VM will work with all its default settings for the variables. This is similar to invoking emacs via emacs -Q. If you ever find a problem with VM’s behavior, it is a good idea to run it without the vm-preferences-file in order to check if the problem might have been caused by the preferences settings.

M-x vm causes VM to visit a folder known as your primary inbox, specified by the variable vm-primary-inbox. If the variable vm-auto-get-new-mail is set non-nil, VM will gather any new mail that has arrived and integrate it into your primary inbox. The default setting for your primary inbox is the local file ~/Mail/inbox, but a variety of other options are available.

VM can work with mail folders saved on the local file system. See Local Folders. It can also work with mail folders stored on remote mail servers, such as POP and IMAP servers. See POP and IMAP Folders. Server folders have the advantage that they can be accessed from multiple locations on the internet. VM might appear to have a bias towards local folders due to its history of development. But it treats server folders with equal facility.

M-x vm-visit-folder (v from within VM) allows you to visit any local mail folder. The folder name will be prompted for in the minibuffer. M-x vm-visit-pop-folder and M-x vm-visit-imap-folder perform similar function for server folders.

Once VM has read the folder and assimilated any new mail, the first new or unread message will be selected, if any. If there is no such message, VM will select whatever the selected message was when this folder was last saved. If this folder has never been visited and saved by VM, then the first message in the folder is selected.

M-x vm-mode can be used on a buffer already loaded into Emacs to put it into the VM major mode so that VM commands can be executed on it. This command is suitable for use in Lisp programs, and for inclusion in auto-mode-alist to automatically start VM on a file based on a particular filename suffix. vm-mode skips some of VM’s start-up procedures (e.g. starting up a summary) to make non-interactive use easier.

The variable vm-startup-with-summary controls whether VM automatically displays a summary of the folder’s contents at startup. A value of nil gives no summary; a value of t always gives a summary. A value that is a positive integer n means that VM should generate a summary if there are n or more messages in the folder. A negative value -n means generate a summary only if there are n or fewer messages. The default value of vm-startup-with-summary is t.

1.1 Local Folders

A local mail folder is simply a file that can be stored on the local file system. VM works with the Unix mbox format to store messages in folders. It can also work with the Babyl format used by the Emacs Rmail package. The subtypes of mboxes handled by VM are listed under Folder types below.

It is a good idea to create directory, e.g., ~/Mail, where all of VM’s local folders will be kept. If you create such a directory, you should set the variable vm-folder-directory to point to it.

A spool file is a file where the mail transport system delivers messages intended for you. On Unix systems, a program called /bin/mail or /bin/mail.local does this delivery. It is also possible for agents such as procmail, filter and slocal to be invoked from a user’s ~/.forward or ~/.qmail files, sorting the incoming mail into separate spool files. On other systems, incoming mail may be delivered to mailboxes on remote mail servers, from where it can be retrieved through protocols like POP and IMAP. No matter what the delivery agent, what all spool files have in common is that mail is delivered into them by one or more entities apart from VM and that all access to spool files must therefore be accompanied by the use of some file locking protocol.

When spool files are on the local file system, VM uses the program movemail, a program distributed with Emacs to extract mail from a spool file. The variable vm-movemail-program specifies the name of the movemail program and defaults to ‘"movemail"’. The variable vm-movemail-program-switches lets you specify some initial command line argument to pass to the movemail program.

VM transfers the mail from a spool file to a folder via a temporary file known as the crash box. The variable vm-crash-box names the crash box file for the primary inbox. Or a crash-box name may be created from vm-crash-box-suffix described below. (see Spool Files.) VM first copies the mail to the crash box, truncates the spool file to zero messages, merges the crash box contents into the primary inbox, and then deletes the crash box. If the system or Emacs should crash in the midst of this activity, any message not present in the primary inbox will be either in the spool file or the crash box. Some messages may be duplicated but no mail will be lost.

If the file named by vm-crash-box already exists when VM is started up, VM will merge that file with the primary inbox before retrieving any new messages from the system mailbox.

Spool Files

Every folder, including the primary inbox, can have one or more spool files associated with it. You make these associations known to VM by setting the variable vm-spool-files.

If you only want to associate spool files with your primary inbox, you can set vm-spool-files to a list of strings. By default, the location of your system mailbox (the spool file that is associated with your primary inbox) is determined heuristically based on what type of system you’re using. VM can be told explicitly where the system mailbox is by setting vm-spool-files like this:

(setq vm-spool-files '("/var/spool/mail/kyle" "~/Mailbox"))

With this setting, VM will retrieve mail for the primary inbox from first /var/spool/mail/kyle and then ~/Mailbox.

If the value of vm-spool-files is nil, a default value for vm-spool-files will be inherited from the shell environmental variables MAILPATH or MAIL if either of these variables are defined. This inheritance happens before your init file is loaded, so setting vm-spool-files in your init file will override any environmental variables.

If you want to associate spool files with folders other than or in addition to the primary inbox, the value of vm-spool-files must be a list of lists. Each sublist specifies three entities, a folder, a spool file and a crash box. When retrieving mail for a particular folder, VM will scan vm-spool-files for folder names that match the current folder’s name. The spool file and crash box found in any matching entries will be used to gather mail for that folder.

For example, you can set vm-spool-files like this

(setq vm-spool-files
      '(
        ("~/INBOX"      "/var/spool/mail/kyle"      "~/INBOX.CRASH")
        ("~/INBOX"      "~/Mailbox"                 "~/INBOX.CRASH")
        ("~/Mail/bugs"  "/var/spool/mail/answerman" "~/Mail/bugs.crash")
       )
)

The folder ~/INBOX has two spool files associated with it in this example, /var/spool/mail/kyle and ~/Mailbox. Another folder, "~/Mail/bugs" has one spool file /var/spool/mail/answerman associated with it. Note that both of the ~/INBOX entries used the same crash box. The crash box can be the same if the folder name is the same. Different folders should use different crashboxes.

An alternate way of specifying folder/spool file associations is to use the variables vm-spool-file-suffixes and vm-crash-box-suffix.

The value of vm-spool-file-suffixes should be a list of string suffixes to be used to create possible spool file names for folders. Example:

(setq vm-spool-file-suffixes '(".spool" "-"))

With vm-spool-file-suffixes set this way, if you visit a folder ~/mail/beekeeping, when VM attempts to retrieve new mail for that folder it will look for mail in ~/mail/beekeeping.spool and ~/mail/beekeeping- in addition to scanning vm-spool-files for matches. The value of vm-spool-files-suffixes will not be used unless vm-crash-box-suffix is also defined, since a crash box is required for all mail retrieval from spool files.

The value of vm-crash-box-suffix should be a string suffix used to create possible crash box file names for folders. When VM uses vm-spool-file-suffixes to create a spool file name, it will append the value of vm-crash-box-suffix to the folder’s file name to create a crash box name. If the value of vm-spool-files-suffixes is nil, then the value of vm-crash-box-suffix is not used by VM.

The idea behind vm-spool-file-suffixes and vm-crash-box-suffix is to give you a way to have many folders with individual spool files associated with them, without having to list them all in vm-spool-files. If you need even more control of spool file and crash box names, use vm-make-spool-file-name and vm-make-crash-box-name. The value of both of these should be a function or the name of a function. When VM visits a folder, it will call the function with the name of the folder as an argument, and the function should return the spool file name or crash box name to be used for that folder.

If your spool file is on another host, VM supports accessing spool files on remote hosts using the POP and IMAP protocols.

POP Spool Files

VM can access spool files on mail servers via the Post Office Protocol (POP). To use a POP mailbox as a spool file, you need to use a POP maildrop specification (maildrop specification, POP and IMAP Folders). Once this is done, VM will retrieve new mail from the POP mailbox in the same way as it retrieves it from system mailbox. The retrieved messages can be automatically removed from the POP mailbox or retained until a later expunge operation.

By default VM will retrieve all the messages from a POP mailbox before returning control of Emacs to you. If the mailbox is large, the wait could be considerable. If you set vm-pop-max-message-size to a positive numeric value, VM will not automatically retrieve messages larger than this size. If VM is retrieving messages because you invoked vm-get-new-mail interactively, then VM will ask whether it should retrieve the large message. If VM is retrieving messages automatically (e.g. vm-auto-get-new-mail is set non-nil) then VM will skip the large message and you can retrieve it later.

The variable vm-pop-messages-per-session controls how many messages VM will retrieve from a POP mailbox before returning control to you. Similarly, the variable vm-pop-bytes-per-session limits the number of bytes VM will retrieve from a POP mailbox before returning control to you. By default, the value of both variables is nil, which tells VM to retrieve all the messages in the POP mailbox regardless of how many messages there are and how large the mailbox is.

After VM retrieves messages from the mailbox, the default action is to leave the original messages on the server unchanged. They can be expunged from the server by running vm-expunge-pop-messages; only those messages that VM has retrieved into the current folder will be expunged.

If you want VM to expunge the messages automatically after retrieving them, you can set vm-pop-expunge-after-retrieving to t. But a better method is to set the variable vm-pop-auto-expunge-alist, which gives you a way to specify, on a per-mailbox basis, which POP mailboxes should have messages automatically removed after retrieving and which ones should leave the messages on the POP server. The value of vm-pop-auto-expunge-alist should be a list of POP mailboxes and values specifying whether messages should be automatically deleted from the mailbox after retrieval. The format of the list is:

((MAILDROP . VAL) (MAILDROP . VAL) ...)

MAILDROP should be a POP mailbox specification as described in the documentation for the variable vm-spool-files. If you have the POP password specified in the vm-spool-files entry, you do not have to specify it here as well. Use ‘*’ instead; VM will still understand that this mailbox is the same as the one in vm-spool-files that contains the password.

VAL should be nil if retrieved messages should be left in the corresponding POP mailbox, t if retrieved messages should be removed from the mailbox immediately after retrieval.

Here is an example:

(setq vm-pop-auto-expunge-alist
   '(
     ("odin.croc.net:110:pass:kyle:*" . nil)  ;; leave message on the server
     ("hilo.harkie.org:110:pass:kyle:*" . t)  ;; expunge immediately
    )
)

IMAP Spool Files

VM can also use IMAP (Internet Message Access Protocol) to retrieve mail from a mail server. As with POP, instead of specifying a local file name in the vm-spool-files definition, you would give an IMAP maildrop specification (maildrop specification, POP and IMAP Folders). Once this is done, VM will retrieve new mail from the IMAP mailbox in the same way as it retrieves it from system mailbox. The retrieved messages can be automatically removed from the IMAP mailbox or retained until a later expunge operation.

The variable vm-imap-messages-per-session controls how many messages VM will retrieve from an IMAP mailbox before returning control to you. Similarly, the variable vm-imap-bytes-per-session limits the number of bytes VM will retrieve from an IMAP mailbox before returning control to you. By default, the value of both variables is nil, which tells VM to retrieve all the messages in the IMAP mailbox regardless of how many messages there are and how large the mailbox is.

After VM retrieves messages from the mailbox, the default action is to leave the original messages on the server unchanged. They can be expunged from the server by running vm-expunge-imap-messages; only those messages that VM has retrieved into the current folder will be expunged.

If you want VM to expunge the messages automatically after retrieving them, you can set vm-imap-expunge-after-retrieving to t. But a better method is to set the variable vm-imap-auto-expunge-alist, which gives you a way to specify, on a per-mailbox basis, which IMAP mailboxes should have messages automatically removed after retrieving and which ones should leave the messages on the IMAP server. The value of vm-imap-auto-expunge-alist should be a list of IMAP mailboxes and values specifying whether messages should be automatically deleted from the mailbox after retrieval. The format of the list is:

((MAILDROP . VAL) (MAILDROP . VAL) ...)

MAILDROP should be an IMAP maildrop specification as described in the documentation for the variable vm-spool-files. If you have the IMAP password specified in the vm-spool-files entry, you do not have to specify it here as well. Use ‘*’ instead; VM will still understand that this mailbox is the same as the one in vm-spool-files that contains the password.

VAL should be nil if retrieved messages should be left in the corresponding IMAP mailbox, t if retrieved messages should be removed from the mailbox immediately after retrieval.

Here is an example:

(setq vm-imap-auto-expunge-alist
   '(
     ;; leave message on the server
     ("imap:odin.croc.net:143:inbox:login:kyle:*" . nil)
     ;; expunge immediately
     ("imap:hilo.harkie.org:143:inbox:login:kyle:*" . t)
    )
)

Multiple access to IMAP spool files

A principal idea behind the IMAP protocol is that messages can be retained on the server so that you can read them from multiple locations, e.g., from office and home, or from other places on the Internet while you travel. If you access your IMAP mailbox from multiple locations then you would need to plan your strategy for expunging messages carefully. For instance, if you access your work mailbox from home, and both your office machine and home machine expunge messages after retrieving them, then some of your mail will end up on your office machine and some on your home machine. That is unlikely to be a successful strategy.

The best way to access IMAP mailboxes from multiple locations is to use the facility of IMAP folders. (See POP and IMAP Folders.) However, if you prefer to download all mail to local folders, then your best bet is to designate one of your machines as the principal location for downloading mail and treat the other machines as temporary mail reading sites. In that case, you should set the principal downloading location to expunge messages on the server and set the other reading sites to leave the messages on the server intact. You can also manually run vm-expunge-imap-messages if you are careful to remember which site should expunge messages and which site should retain them.

VM remembers the messages you have downloaded from an IMAP spool file so that it can avoid downloading them again on your next visit. The list of these messages is written into a special mail header titled X-VM-IMAP-Retrieved in your mail folder. When you expunge IMAP messages, their entries are deleted from the list. However, when you designate one of your machines as a reading site and never expunge messages from there, then the X-VM-IMAP-Retrieved header on that machine will only grow over time. When the list gets excessively long, it will slow down the saving of folders.

To avoid the problem, you should prediodically run the command vm-prune-imap-retrieved-list. It will examine the IMAP server to see which messages still exist and retain only their information in the X-VM-IMAP-Retrieved header.

Index Files

VM can create an index file, which describes the messages contained in a folder. If such an index file exists and is up to date, then VM will read the contents of the index file first while starting up in order to quickly form the summary of the folder.

To use this feature, set the variable vm-index-file-suffix to a file name extension, e.g.,

(setq vm-index-file-suffix "idx")

Folder types

VM can handle a variety of formats for mail folders, which differ in details. The variable vm-default-folder-type can be used to set the default format that is suitable for your environment. This setting is used when VM creates new folders.

When VM reads a folder from the file system, it examines contents of the folder to determine what format it is stored in and decodes it appropriately. (However, such inference is not fully automatic. See below.)

After a folder is loaded into VM, you can convert it to a different format using the command vm-change-folder-type. It is a good idea to keep all your mail folders in a single format in order to avoid incompatibilities.

The system default format is referred to as From_. It is the Unix mbox format described RFC 4155. In this format, a leading separator line and a trailing separator line are added to each message. The leading separator line starts with the string “From ”. The trailing separator line is a blank line. VM actually adds two blank lines at the end for clarity.

A variant of this format is referred to as BellFrom_. It has a leading separator line that starts with the string “From ”. However, it does not have a trailing blank line.

Since VM cannot reliably infer whether a mail folder is of type From_ or BellFrom_, you must tell VM which one your system uses by setting the variable vm-default-From_-folder-type. Some of the old folders created by VM prior to 2000 were in the BellFrom_ format. If you will be using both From_ and BellFrom_ style folders, it is not possible to choose an appropriate setting for this variable. It is recommended that you convert all the old BellFrom_ folders to the From_ format using the command vm-change-folder-type.

Solaris, System V and AIX operating systems use another variant of the mbox format where the content-length is specified in the “From ” line. VM refers to this format as From_-with-Content-Length. Since the content lengths may be unreliable, you must also set the variable vm-trust-From_-with-Content-Length to a non-Nil value in order to convince VM that you really want to use this format.

Two additional formats are mmdf used by MMDF systems and babyl used by the Emacs Rmail mode. These formats are recognized automatically when read from the file system.

1.2 POP and IMAP Folders

VM supports accessing remote mailboxes on mail servers via the Post Office Protocol (POP) and the Internet Message Access Protocol (IMAP). Instead of a local file name, you can set the vm-primary-inbox to a string that tells VM how to access a server mailbox. Called a maildrop specification, the string is of one of the following formats:

``pop:HOST:PORT:AUTH:USER:PASSWORD''
``imap:HOST:PORT:MAILBOX:AUTH:USER:PASSWORD''

Remote mailboxes accessed by VM in this fashion are referred to as server folders (and POP folders or IMAP folders, more specifically).

VM retrieves mail from the server folders into internal Emacs buffers for its normal operation. It also saves copies of the folders on the local file system for speed of operation. These are referred to as cache folders. However, the only permanent copies of the folders are on the mail server. This should be contrasted with using server mailboxes as spool files (see POP Spool Files and see IMAP Spool Files), where the permanent folders are on the local file system and only the incoming mail is held on the servers.

Server folders have the advantage that they can be transparently accessed from multiple locations on the internet. However, you must ensure that you have access to enough storage on the mail server to store all your email.

Maildrop specification

The format of a POP or IMAP maildrop specification is as follows:

``pop:HOST:PORT:AUTH:USER:PASSWORD''
``imap:HOST:PORT:MAILBOX:AUTH:USER:PASSWORD''

Replace ‘pop’ in the example with ‘pop-ssl’ to have VM speak POP over an SSL connection. Use ‘pop-ssh’ to use POP over an SSH connection. Similarly, replace ‘imap’ with ‘imap-ssl’ or ‘imap-ssh’, as needed.

SSL refers to a protocol called secure sockets layer, which allows you to securely communicate with a mail server using encryption technology. A newer version of the same protocol is called TLS (transport layer security). We refer to both of them as “SSL” in this manual.

For SSL, you must either be using a version of Emacs that has SSL capability or have the stunnel program installed and the variable vm-stunnel-program naming it. The default value of this variable, ‘"stunnel"’, should be sufficient if the program is installed in your normal command search path. In order to use the built-in SSL capability of your Emacs version, set vm-stunnel-program to nil.

For SSH, you must have the ssh program installed and the variable vm-ssh-program must name it in order for POP/IMAP over SSH to work. When VM makes the SSH connection it must run a command on the remote server so that the SSH session is maintained long enough for the POP/IMAP connection to be established. By default that command is ‘"echo ready; sleep 10"’, but you can specify another command by setting vm-ssh-remote-command. Whatever command you use must produce some output and hold the connection open long enough for VM to establish a port-forwarded connection to the mail server. (SSH must be able to authenticate without a password, which means you must be using .shosts authentication or RSA.)

HOST is the host name of the mail server.

PORT is the TCP port number to connect to. The normal port numbers are:

MAILBOX is the name of the mailbox on the IMAP server. This should be ‘"inbox"’, to access your default IMAP mailbox on the server. No MAILBOX component is needed for POP maildrops because POP does not support multiple mailboxes.

AUTH is the authentication method used to convince the server you should have access to the mailbox. Acceptable values for POP are ‘pass’, ‘rpop’ and ‘apop’. For ‘pass’, the PASSWORD is sent to the server with the POP PASS command. For ‘rpop’, the PASSWORD should be the string to be sent to the server via the RPOP command. In this case the string is not really a secret; authentication is done by other means. For ‘apop’, an MD5 digest of the PASSWORD appended to the server time-stamp will be sent to the server with the APOP command. If Emacs does not have built in MD5 support, you will have to set the value of vm-pop-md5-program appropriately to point at the program that will generate the MD5 digest that VM needs.

Acceptable values of AUTH for IMAP are ‘"preauth"’, ‘"cram-md5"’, and ‘"login"’. ‘"preauth"’ causes VM to skip the authentication stage of the protocol with the assumption that the session was authenticated in some way external to VM. The hook vm-imap-session-preauth-hook is run, and it is expected to return a process connected to an authenticated IMAP session. ‘"cram-md5’ tells VM to use the CRAM-MD5 authentication method as specified in RFC 2195. The advantage of this method over the ‘"login"’ method is that it avoids sending your password over the net unencrypted. Not all IMAP servers support ‘"cram-md5"’; if you’re not sure, ask your mail administrator or just try it. The other value, ‘"login"’, tells VM to use the IMAP LOGIN command for authentication, which sends your user name and password in clear text to the server.

USER is the user name used in authentication methods that require such an identifier. ‘"login"’ and ‘"cram-md5"’ use it currently.

PASSWORD is the secret shared by you and the server for authentication purposes. How it is used depends on the value of the AUTH parameter. If the PASSWORD is ‘*’, VM will prompt you for the password the first time you try to retrieve mail from the mailbox. If the password is valid, VM will not ask you for the password again during this Emacs session.

If your environment has the EasyPG utility and your version of Emacs supports it, i.e., has the ‘epa-file’ and ‘auth-source’ libraries, then you can store password information in a file such as .authinfo.gpg. The ‘EasyPG’ protocol allows you to store this information in an encrypted form so that it cannot be read by third parties. Each line in the .authinfo.gpg file should be of the form

machine HOST login USER password PASSWORD port PORT

where HOST, USER, PASSWORD and PORT are as detailed above. Ensure that the variable auth-sources is customized to refer to your authinfo file. See Help for users in Emacs auth-source. Then VM will read passwords from the file and you don’t need to type them in when accessing mail servers.

If you have multiple login accounts on the same HOST then VM will only use the first login listed in the authinfo file. To allow for multiple logins, the HOST entry in the authinfo line can be replaced by an account name as defined internally in VM. These account names are defined via the variables vm-pop-folder-alist and vm-imap-account-alist, described below.

Troubleshooting mail servers

Since a number of components have to be brought together to establish connections to mail servers, it is not uncommon for problems to arise.

To find out what could be going wrong, you can look at the Emacs buffer that store a trace of the session with mail server. Such buffers have names beginning with “trace of POP session” or “trace of IMAP session”. There could be multiple buffers of this kind for different servers and multiple sessions. In the trace buffer, you will find the commands that VM sent to the server and the responses it has received. Typical problems are protocol mismatches between VM and the mail server, or malfunctions in other components such as the stunnel program.

The variables vm-pop-keep-trace-buffer and vm-imap-keep-trace-buffer specify how many trace buffers to keep for such server sessions. The default is 1. Setting these variables to nil will have the effect that no trace buffers are kept.

POP Folders

The command vm-visit-pop-folder allows you to visit a POP mailbox as a folder. When you visit a POP folder, VM will download copies of the messages that it finds there for you to read. These messages are saved locally in cache folders, in the directory specified by vm-pop-folder-cache-directory (or vm-folder-directory if the former is not defined). If you delete and expunge messages in the folder, the corresponding messages on the POP server will be removed when you save the changes with vm-save-folder.

Message attributes (new, replied, filed, etc.) and labels cannot be stored on the POP server but they will be maintained in the cache folder. This means that if you access the same POP mailbox from multiple locations on the internet, you will see different attributes at different locations. To be able to store message attributes and labels on the server, you should use IMAP folders (IMAP Folders) resident on an IMAP server.

In order for VM to know about POP folders that you can access, you must declare them by setting the variable vm-pop-folder-alist. The variable’s value should be an associative list of the form:

 ((POPDROP NAME) ...)

POPDROP is a POP maildrop specification (maildrop specification).

NAME is a string that should give a less cumbersome name that you will use to refer to this maildrop when using vm-visit-pop-folder.

For example:

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

‘Yahoo! mail’ and ‘local mail’ are what you would type when vm-visit-pop-folder asks for a folder name. There is no need to specify the password for POP accounts in this definition.

IMAP Folders

The command vm-visit-imap-folder allows you to visit an IMAP mailbox as a folder. The name of the IMAP mailbox should be input via the minibuffer in the format account-name:folder-name. Here, “account-name” is the name of an IMAP account declared in vm-imap-account-alist and “folder-name” is the name of an IMAP mailbox in this account.

When you visit an IMAP folder, VM will download copies of the messages that it finds there for you to read. These messages are saved locally in a cache folder on the disk, in the directory specified by vm-imap-folder-cache-directory (or vm-folder-directory if the former is not defined). If you delete and expunge messages, these changes are made to both the cache folder and the folder on the IMAP server when saved with vm-save-folder.

Message attributes (new, replied, filed, etc.) are stored on the IMAP server and are also cached locally. Message labels are also stored on the IMAP server as user-defined permanent flags. (This assumes that the IMAP server has the ability to store user-defined permanent flags.)

In order for VM to know about IMAP accounts that you can access, you must declare them by setting the variable vm-imap-account-alist. The variable’s value should be an associative list of the form:

 ((IMAPDROP NAME) ...)

IMAPDROP is an IMAP maildrop specification (maildrop specification).

NAME is a string that should give a less cumbersome name that you will use to refer to this maildrop when using vm-visit-imap-folder. For example:

(setq vm-imap-account-alist
      '(
        ("imap-ssl:mail.foocorp.com:993:*:login:becky:*" "becky")
        ("imap:crickle.lex.ky.us:143:*:login:becky:*" "crickle")
       )
)

The mailbox and password fields (‘*’ in the example) are ignored. When vm-visit-imap-folder asks for a folder name, you enter an account name followed by “:” and a folder name. Any folder that is accessible to you on the IMAP server can be specified. For example, becky:inbox or crickle:drafts.

When you visit an IMAP folder inside VM, the folder is referred to by its folder name as it exists on the server. For example, visiting becky:INBOX creates a folder called INBOX inside VM. If you visit multiple IMAP accounts within a VM session, then you would end up with multiple folder buffers all named INBOX. To avoid this problem, you can set the variable vm-imap-refer-to-inbox-by-account-name to t, which causes the INBOX folder buffers to be named by their IMAP account names instead. For example, visiting becky:INBOX would create a VM folder named becky and visiting crickle:INBOX would create a VM folder named crickle.

The customization variable vm-imap-server-list, used in older versions of VM, is deprecated. Please use vm-imap-account-alist instead.

IMAP Synchronization

The cache folder and the folder on the IMAP server are partially synchronized every time vm-get-new-mail is invoked. This involves (i) writing the changed attributes and labels to the server, (ii) updating the attributes and labels in the cache folder based on the server data, (iii) expunging messages in the cache folder that have been expunged on the server, and finally, (iv) retrieving any new messages on the server. The variable vm-imap-sync-on-get specifies whether such synchronization should be done as part of vm-get-new-mail. If the variable is set to nil then vm-get-new-mail simply retrieves any new messages.

The cache folder and the folder on the IMAP server are also synchronized every time vm-save-folder is invoked. This involves (i) writing the changed attributes and labels to the server, (ii) updating the attributes and labels in the cache folder based on the server data, (iii) expunging messages in the cache folder that have been expunged on the server, (iv) deleting and expunging the locally expunged messages on the server folder, and finally, (v) saving a copy of the folder on the file system.

The command vm-imap-synchronize can always be used to perform full synchronization with the server.

1.3 Thunderbird Folders

VM can work with local folders managed by Mozilla Thunderbird. You can find the location of Thunderbird’s folders by examining the Account Settings for “Local Folders” inside Thunderbird.

Thunderbird stores the folders in the ‘From_’ folder type. See Folder types. Within such folders, Thunderbird stores the message status flags (message attributes such as whether a message is read, replied to, deleted etc.) under special header fields called X-Mozilla-Status and X-Mozilla-Status2. In addition to these headers, Thunderbird also stores a quick copy of the message status flags in a separate file with the extension .msf.

When you visit a Thunderbird folder, VM reads the status flags stored in the special headers and uses them for processing. As you make changes to the folder by reading messages, replying to them or deleting them, the changes are propagated to the Thunderbird status flags and written to the disk when saved. VM also deletes the .msf file maintained by Thunderbird so that Thunderbird will recompute the status information from the headers. Thus, the changes made to the Thunderbird folders will be visible inside Thunderbird.

The variable vm-sync-thunderbird-status controls how VM deals with Thunderbird folders. The default value t gives the behavior described above. You can also set it to 'read-only, in which case VM reads the Thunderbird status flags, but makes no changes to them. So, the changes made to the folders will be lost after you quit VM. If you set it to nil, then VM refrains from reading and writing the Thunderbird status flags. In this case, the changes made to the folders are visible inside VM even after revisiting, but they will have no effect for Thunderbird.

WARNING: Keep in mind that all this applies to changes to message attributes only. If you expunge a folder, then the deleted messages are physically purged from the folder. They will be lost both inside VM as well as Thunderbird.

The variable vm-sync-thunderbird-status is a buffer-local variable. You may set its default value in your .vm file. To change it in a running Emacs session, you must use setq-default. See Local Variables in Gnu Emacs manual.

A new experimental feature allows you to visit Thunderbird’s local folders using the command M-x vm-visit-thunderbird-folder. This works the same way as vm-visit-folder except for the difference that the default directory for visiting folders as well as saving messages will be taken from the variable vm-thunderbird-folder-directory. You should set this variable to the directory where Thunderbird stores its folders. The folders visited using M-x vm-visit-folder will continue to be found in vm-folder-directory, thus allowing you to manage the two spaces separately.

If, on the other hand, you want to maintain a single space where VM and Thunderbird can jointly operate, then you should set the variable vm-folder-directory to point to that place and leave vm-thunderbird-folder-directory with its default value of nil.

1.4 External Messages

Under certain circumstances, it is possible to maintain VM folders in which only the headers of messages are loaded into the Folder buffer. The message bodies are retained in external sources (file system or remote servers) and fetched on demand when the messages are viewed or other operations are performed on them. Using external messages results in a smaller folder size and allows a faster operation on machines with limited resources. However, the fetching of message bodies on demand can introduce short delays when messages are viewed. It is also not possible to search in the message bodies of external messages.

To enable external messages, set the variable vm-enable-external-messages to a list of contexts in which external messages may be maintained by VM.

As of version 8.2.0, the only context in which external messages are implemented is that of IMAP folders. Setting vm-enable-external-messages to (imap) enables IMAP messages to be maintained externally. When new messages are retrieved, this causes all messages with size below vm-imap-max-message-size to be loaded immediately, and larger messages will be left on the server to be fetched on demand. To treat all messages as external messages, you can set vm-imap-max-message-size to 0.

After fetching the bodies of external messages, VM stores them in the Folder buffer temporarily, so that repeated fetching is avoided. The variable vm-fetched-message-limit controls how many message bodies are stored in this way. You can set it to an integer (10 is the default), or to nil, signifying that there is no limit. All the fetched message bodies are flushed before folders are saved to disk.

You can manually load message bodies into the Folder using the command o (vm-load-message). The command O (vm-unload-message) unloads a previously loaded message body. Both the commands can take numerical prefix arguments or operate on marked messages. Note that “loading” a message body is different from on demand “fetching”. Loaded messages are permanently stored in the Folder buffer and written to disk when the folder is saved. In contrast, fetched message bodies are always discarded before writing to disk. The command vm-refresh-message reloads an already loaded message with a fresh copy retrieved from the server.

1.5 Getting New Mail

Pressing g runs vm-get-new-mail, which will retrieve mail from all the spool files associated with the current folder. See Local Folders. For POP and IMAP folders, any newly arrived messages at the mail server will be incorporated into the local copy of the folders.

If the value of the variable vm-auto-get-new-mail is non-nil VM will retrieve mail for a folder whenever the folder is visited. If the value is a positive integer n, VM will also check for new mail every n seconds for all folders currently being visited. If new mail is present, VM will retrieve it.

If the value of the variable vm-mail-check-interval is a positive integer n, VM will check for new mail every n seconds, but instead of retrieving mail, the word “Mail” will appear on the Emacs mode line of folders that have mail waiting. Normally, once VM finds new mail, it will turn on the “Mail” indicator and refrain from checking again until you retrieve the new mail. However, if multiple mail clients are trying to retrieve mail from the same spool, it is possible that the new mail might get retrieved into another mail client and your “Mail” indicator won’t reflect the situation. If you need to be particular about new mail in such a situation, then you should set the variable vm-mail-check-always.

1.6 Crash Recovery

When Emacs crashes, its last action before dying is to try to write out an auto-save file that contains changes to files that you were editing. VM folders are file buffers inside Emacs, so folders are auto-saved also. For VM folders, changes means attribute changes, label additions and deletions, message edits, and expunges. VM keeps track of whether a message is new or old, whether it has been replied to, whether it is flagged for deletion and so on, by writing special headers into the folder buffer. These headers are saved to disk when you save the folder. If Emacs crashes before the folder has been saved, VM may forget some attribute changes unless they were written to the auto-save file.

Note that when VM retrieves mail from spool files it always writes them to disk immediately and at least one copy of the message is on disk at all times. So while you can lose attribute changes from crashes, you should not lose messages unless the disk itself is compromised.

Recovering Folders

When you visit a folder, VM checks for the existence of an auto-save file that has been modified more recently than the folder file. If such an auto-save file exists, there is a good chance that Emacs or your operating system crashed while VM was visiting a folder. VM will then write a message to the echo area informing you of the existence of the auto-save file and visit the folder in read-only mode. Visiting the folder in read-only mode prevents you from modifying the folder, which in turn prevents Emacs from wanting to write new changes to the auto-save file. VM will not retrieve new mail for a folder that is in read-only mode. VM also skips summary generation and MIME decoding to help catch your attention.

If you want to recover the lost changes, run M-x vm-recover-folder or use the Recover Folder entry in Folder menu. At the ‘Recover File:’ prompt press RET. Emacs’s built-in recover-file command is not recommended for this purpose because VM is unable to obtain reliable data regarding mail folders from Emacs.

In response to vm-recover-folder, Emacs will display a detailed directory listing showing the folder file and the auto-save file and ask you whether you want to recover from the auto-save file. A good rule of thumb is to answer “yes” if the auto-save file is larger than the folder file. If the auto-save file is significantly smaller, Emacs might not have completed writing the auto-save file during the previous crash. Or it could be that the smaller auto-save file reflects the results of an expunge that you had not yet committed to disk before the crash. If so, answering “no” means you might have to do that expunge again, but this is better than not knowing whether the auto-save file was truncated.

Assuming you answered “yes”, the folder buffer’s contents will be replaced by the contents of the auto-save file and VM will re-parse the folder. At this point the contents of the folder buffer and the disk copy of the folder are different. Therefore VM will not get new mail for this folder until the two copies of the folder are synchronized. When you are satisfied that the recovered folder is whole and intact, type S to save it to disk. After you do this, VM will allow you to use g to retrieve any new mail that has arrived in the spool files for the folder.

Assuming you answered “no” to the recovery question, you should type C-x C-q, which is bound to vm-toggle-read-only in VM folder buffers. The folder will be taken out of read-only mode and you can read and retrieve your mail normally, ignoring the auto-save file that is still on disk.

If you are visiting a POP or IMAP folder (rather than a local folder) that was modified during a previous crash, the process of recovery is similar. However, there will be less useful information in the auto-save file in this case. When you synchronize an IMAP folder with the server, only the changes made during the current VM session are saved to the server. Changes stored in the auto-save file were made in a previous session of VM and, so, cannot be saved to the server. So, saying “no” to the recovery question and toggling the read-only status (C-x C-q) is a better option in the case of server folders.

Recovering Message Compositions

Any messages you were in the midst of composing when Emacs crashed, would also have auto-save files in the disk. They would be saved in the vm-mail-auto-save-directory, if you have set that variable, or vm-folder-directory, or the directory that was current when you started composing the message. You can visit the auto-save file, which would get loaded as a text file by default, and then run M-x mail-mode. VM’s mail-mode command keys are not available in this mode. The best option is to run M-x vm-postpone-message to save the unfinished message composition and then continue it using vm-continue-postponed-message. See Postponing message composition.

Recovering Sessions

Emacs also provides a way to recover the entire Emacs session after a crash. See Recover in the GNU Emacs Manual. However, the Emacs recover-session command will recover VM folders as if they were ordinary files. As mentioned above, this is not a good method of recovering VM folders. You should use vm-recover-folder command instead. So, when Emacs recover-session command asks you whether to recover a VM folder, the best option is to answer “no”. Then you should recover the folders separately, using the vm-recover-folder command.

If you do answer “yes”, then Emacs loads the auto-save file into a buffer. The auto-save file still exists on the disk, but it will get deleted when you save the buffer. So, you should examine the folder before you save it. Run M-x vm-mode in the buffer corresponding to the VM folder, make sure that it is not damaged, and then save the folder. If you do not believe that the auto-saved version is good, you can kill the buffer. At this point, VM asks you for confirmation whether you really want to kill the buffer and, secondly, whether you want to delete the auto-save file. If you answer “yes” to the last question, then the auto-saved folder will be gone for ever.

Reverting a Folder

If you have made changes to a mail folder which you would like to cancel and go back to the version currently on the disk, you can use the function vm-revert-folder or the “Revert Folder” entry in the Folder menu. (Emacs’s built-in revert-file is not recommended.)