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. Since VM has well over one hundred configuration variables, use of the `~/.vm' can considerably reduce clutter in the `.emacs' file. You can reload this file by typing L (vm-load-init-file) from within VM.

M-x vm causes VM to visit a file known as your primary inbox. If the variable vm-auto-get-new-mail is set non-nil, VM will gather any mail present in your system mailbox and integrate it into your primary inbox. The default name of your primary inbox is `~/INBOX', but VM will use whatever file is named by the variable vm-primary-inbox.

VM transfers the mail from the system mailbox to the primary inbox via a temporary file known as the crash box. The variable vm-crash-box names the crash box file. VM first copies the mail to the crash box, truncates the system mailbox 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 system mailbox 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.

M-x vm-visit-folder (v from within VM) allows you to visit some other mail folder than the primary inbox. The folder name will be prompted for in the minibuffer.

Once VM has read the folder, any spool files associated with the folder are checked for new messages if vm-auto-get-new-mail is non-nil. See section 1.1 Spool Files. After this, 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 startup 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 on 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 Spool Files

VM leaves the task of accessing spool files to `movemail', a program distributed with Emacs that is written for this purpose. 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.

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 folder `/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.

1.2 POP Spool Files

``pop:HOST:PORT: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.

For SSL, you must have the stunnel program installed and the variable vm-stunnel-program must name it in order for POP over SSL to work. The default value of this variable, `"stunnel"', should be sufficient if the program is installed in your normal command search path.

For SSH, you must have the ssh program installed and the variable vm-ssh-program must name it in order for POP over SSH to work. When VM makes the SSH connection it must run a command on the remote host so that the SSH session is maintained long enough for the POP 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 POP server.

HOST is the host name of the POP server. PORT is the TCP port number to connect to (should normally be 110). For POP over SSL connections the standard port is 995. USER is the user name sent to the server. 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 maildrop. If the password is valid, VM will not ask you for the password again during this Emacs session.

AUTH is the authentication method used to convince the server you should have access to the maildrop. Acceptable values 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 timestamp will be sent to the server with the APOP command. If Emacs does not have bulit 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.

By default VM will retrieve all the messages from a POP maildrop before returning control of Emacs to you. If the maildrop 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 maildrop before returning control to you. Similarly, the variable vm-pop-bytes-per-session limits the number of bytes VM will retrieve from a POP maildrop 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 maildrop regardless of how many messages there are and how large the maildrop is.

After VM retrieves messages from the maildrop, the default action is to delete the messages from there. If you want VM to leave messages in the remote maildrop until you explicitly request their removal, set vm-pop-expunge-after-retrieving to nil. Messages will not be removed from the maildrop until you run vm-expunge-pop-messages; only those messages that VM has retrieved into the current folder will be expunged.

The variable vm-pop-auto-expunge-alist gives you a way to specify on a per-maildrop basis which POP maildrops have messages automatically removed when retrieved and which ones 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:

((MAILBOX . VAL) (MAILBOX . VAL) ...)

MAILBOX should be an POP maildrop 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
    )
)

1.3 IMAP Spool Files

An IMAP maildrop specification has the following format:

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

Replace `imap' in the example with `imap-ssl' to have VM speak IMAP over an SSL connection. Use `imap-ssh' to use IMAP over an SSH connection.

For SSL, you must have the stunnel program installed and the variable vm-stunnel-program must name it in order for IMAP over SSL to work. The default value of this variable, `"stunnel"', should be sufficient if the program is installed in your normal command search path.

For SSH, you must have the ssh program installed and the variable vm-ssh-program must name it in order for IMAP over SSH to work. When VM makes the SSH connection it must run a command on the remote host so that the SSH session is maintained long enough for the 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 IMAP 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 IMAP server.

PORT is the TCP port number to connect to (should normally be 143). For IMAP over SSL connections the standard port is 993.

MAILBOX is the name of the mailbox on the IMAP server. This should be `"inbox"', to access your default IMAP maildrop on the server.

AUTH is the authentication method used to convince the server you should have access to the maildrop. Acceptable values 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 specificed 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 username and password in cleartext 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. If the PASSWORD is `*', VM will prompt you for the password the first time you try to retrieve mail from the maildrop. If the password is valid, VM will not ask you for the password again during this Emacs session.

By default VM will retrieve all the messages from an IMAP maildrop before returning control of Emacs to you. If the maildrop is large, the wait could be considerable. If you set vm-imap-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-imap-messages-per-session controls how many messages VM will retrieve from an IMAP maildrop before returning control to you. Similarly, the variable vm-imap-bytes-per-session limits the number of bytes VM will retrieve from an IMAP maildrop 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 maildrop regardless of how many messages there are and how large the maildrop is.

After VM retrieves messages from the maildrop, the default action is to delete the messages from there. If you want VM to leave messages in the remote maildrop until you explicitly request their removal, set vm-imap-expunge-after-retrieving to nil. Messages will not be removed from the maildrop until you run vm-expunge-imap-messages; only those messages that VM has retrieved into the current folder will be expunged.

The variable vm-imap-auto-expunge-alist gives you a way to specify on a per-maildrop basis which IMAP maildrops have message automatically removed when retrieved and which ones 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:

((MAILBOX . VAL) (MAILBOX . VAL) ...)

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

1.4 POP Folders

VM's traditional mode of operation is to treat all remote mail sources as spool files, pulling all mail down from remote sources into local folders and deleting the remote copies. But sometimes it is more convenient to treat a remote mail source as a folder instead of a spool file, manipulating the remote source as if it were a folder instead of just a holding area for incoming messages.

The command vm-visit-pop-folder allows you to visit a POP mailbox as if it were a folder. When you visit a POP folder, VM will download copies of the messages that it finds there for you to read. 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 locally, just as they are for ordinary folders.

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 in the same format used by vm-spool-files.

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.

1.5 IMAP Folders

VM's traditional mode of operation is to treat all remote mail sources as spool files, pulling all mail down from remote sources into local folders and deleting the remote copies. But sometimes it is more convenient to treat a remote mail source as a folder instead of a spool file, manipulating the remote source as if it were a folder instead of just a holding area for incoming messages.

The command vm-visit-imap-folder allows you to visit a IMAP mailbox as if it were a folder. When you visit a IMAP folder, VM will download copies of the messages that it finds there for you to read. If you delete and expunge messages in the local copy of the folder, the corresponding messages on the IMAP server will be removed when you save the changes with vm-save-folder.

Message attributes (new, replied, filed, etc.) are stored on the IMAP server and are also cached locally. Labels cannot be stored on the IMAP server but you can use them lcoally.

In order for VM to know about IMAP servers that you can access, you must declare them by setting the variable vm-imap-server-list. The variable's value should be a list of the form:

 (IMAPDROP IMAPDROP ...)

IMAPDROP is a IMAP maildrop specification in the same format used by vm-spool-files.

For example:

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

The mailbox (`inbox' in the example) is ignored; when when vm-visit-imap-folder asks for a folder name you can enter any folder that is acessible to you on the IMAP server.

1.6 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 section 1.1 Spool Files. For POP folders, any newly arrived messages at the POP server will be incorporated into the local copy of the POP folder.

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.

1.7 Crash Recovery

When Emacs crashes, its last action before dying is to try to write out an autosave file that contains changes to files that you were editing. VM folders are file buffers inside Emacs, so folders are autosaved also. Changes, with regard to VM folders, 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 autosave 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.

When you visit a folder, VM checks for the existence of an autosave file that has been modified more recently than the folder file. If such an autosave 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 autosave 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 autosave 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 recover-file or use the Recover toolbar button. At the `Recover File: ' prompt press RET. Emacs will then display a detailed directory listing showing the folder file and the autosave file and ask if you want to recover from the autosave file. A good rule of thumb is to answer "yes" if the autosave file is larger than the folder file. If the autosave file is significantly smaller, Emacs may not have completed writing the autosave file. Or it could be that the smaller autosave 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 autosave file was truncated.

Assuming you answered "yes", the folder buffer's contents will be replaced by the contents of the autosave file and VM will reparse 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.