html2 VM User's Manual: 1. Starting Up
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 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 section Local Folders. It can also work with mail folders stored on remote mail servers, such as POP and IMAP servers. See section Server 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 in the documentation of the variable vm-default-folder-type.

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, although agents such as ‘procmail’, ‘filter’ and ‘slocal’ can be invoked from a user’s ‘~/.forward’ or ‘~/.qmail’ files. On other systems, incoming mail is typically 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.

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.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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, Server 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
    )
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

IMAP Spool Files

VM can also use the IMAP 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, Server 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)
    )
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 section Server 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Server 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. However, the only permanent copies of the folders are on the mail server. This should be contrasted with using server mailboxes as spool files ( POP Spool Files and IMAP Spool Files), where the permanent folders are on the local file system and only 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

For SSL, you must have the stunnel program installed and the variable vm-stunnel-program must name it in order for POP/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 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:

110for POP
995for POP over SSL
143for IMAP
993for 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 the file system, 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 local copy. 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 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 local copy of the 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.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

IMAP Synchronization

The local copy 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 local copy based on the server data, (iii) expunging messages in the local copy that have been expunged on the server (through perhaps a concurrent access to the IMAP folder), 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 local copy 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 local copy based on the server data, (iii) expunging messages in the local copy that have been expunged on the server (through perhaps a concurrent access to the IMAP folder), (iv) deleting the locally expunged messages on the server, 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.

After fetching messages from the IMAP server into the local copy, it is possible to visit the local copy as if it were a normal folder. VM can operate on the local copy without contacting the server. This allows offline operation on the mail folders. When the IMAP server is connected again, one should do the vm-imap-synchronize command with a prefix argument. This causes all the message attributes and labels to be written to the server, since it may not be known which of them have actually changed during the offline operation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 section 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 (emacs)Locals section ‘Local Variables’ in Gnu Emacs manual.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 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 Local Folders. 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 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 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 the mail folders from Emacs.) 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 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.

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


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on April 30, 2013 using texi2html 1.82.