## 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:

110 | for POP
995 | for POP over SSL
143 | for IMAP
993 | for IMAP over SSL

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.)