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
• POP Spool Files
• IMAP Spool Files
• Index Files
• Folder types

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

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

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

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

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

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

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

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

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
• Troubleshooting mail servers
• POP Folders
• IMAP Folders
• IMAP Synchronization

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

machine HOST login USER password PASSWORD port PORT

 ((POPDROP NAME) ...)

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

 ((IMAPDROP NAME) ...)

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

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. You can visit any of the folders in that directory using VM and make changes. Such changes will be propagated to Thunderbird in an appropriate way.

Alternatively, you can set the variable vm-thunderbird-folder-directory to the directory where Thunderbird stores its folders, and use the command M-x vm-visit-thunderbird-folder to visit its folders. This works the same way as vm-visit-folder except that the default directory for visiting folders as well as saving messages will be the value of vm-thunderbird-folder-directory. On the other hand, the folders visited using vm-visit-folder will continue to be in vm-folder-directory, 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 that place and leave vm-thunderbird-folder-directory with its default value of nil.

• Differences in folder summary
• How the inter-operation works

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.

Normally, the messages that are not present in the folder are fetched automatically when an attempt is made to view them. You can disable this by setting the variable vm-external-fetch-message-for-presentation to nil. In that case, the messages are displayed with an empty message body. You can load the missing message body using the o command described below.

After fetching the bodies of external messages, VM stores them in the Folder buffer temporarily, so that repeated fetching is avoided. The variable vm-external-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 removed from the folders before they 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
• Recovering Message Compositions
• Recovering Sessions
• Reverting a Folder

3.1 Previewing

Previewing means showing you a small portion of a message and allowing you to decide whether you want to read it. Typing SPC exposes the body of the message, and from there you can repeatedly type SPC to page through the message.

By default, the sender, recipient, subject and date headers are shown when previewing; the rest of the message is hidden. This behavior may be altered by changing the settings of three variables: vm-visible-headers, vm-invisible-header-regexp and vm-preview-lines.

If the value of vm-preview-lines is a number, it tells VM how many lines of the text of the message should be visible. The default value of this variable is 0. If vm-preview-lines is nil, then previewing is not done at all; when a message is first presented it is immediately exposed in its entirety and is flagged as read. If vm-preview-lines is t, the message body is displayed fully but the message is not flagged as read until you type SPC.

The value of vm-visible-headers should be a list of regular expressions matching the beginnings of headers that should be made visible when a message is presented. The regexps should be listed in the preferred presentation order of the headers they match.

If non-nil, the variable vm-invisible-header-regexp specifies what headers should not be displayed. Its value should be a string containing a regular expression that matches all headers you do not want to see. Setting this variable non-nil implies that you want to see all headers not matched by it; therefore the value of vm-visible-headers is only used to determine the order of the visible headers in this case. Headers not matched by vm-invisible-header-regexp or vm-visible-headers are displayed last.

If you change the value of either vm-visible-headers or vm-invisible-header-regexp in the middle of a VM session the effects will not be immediate. You will need to use the command vm-discard-cached-data on each message (bound to j by default) to force VM to rearrange the message headers. A good way to do this is to mark all the messages in the folder and apply vm-discard-cached-data to the marked messages. See Selecting Messages.

Another variable of interest is vm-highlighted-header-regexp. The value of this variable should be a single regular expression that matches the beginnings of any header that should be presented in inverse video when previewing. For example, a value of ‘"^From\\|^Subject"’ causes the From and Subject headers to be highlighted. Highlighted headers will be displayed using the face specified by vm-highlighted-header-face, which defaults to ’bold.

By default, VM will not preview messages that are flagged as read. To have VM preview all messages, set the value of vm-preview-read-messages to t.

Typing t (vm-expose-hidden-headers) makes VM toggle between exposing and hiding headers that would ordinarily be hidden.

3.2 Paging

Typing SPC during a message preview exposes the body of the message. If the message was new or previously unread, it will be flagged “read”. At this point you can use SPC to scroll forward, and DEL to scroll backward a windowful of text at a time. A prefix argument n applied to these commands causes VM to scroll forward or backward n lines. Typing space at the end of a message moves you to the next message. If the value of vm-auto-next-message is nil, SPC will not move to the next message; you must type n explicitly.

If the value of vm-honor-page-delimiters is non-nil, VM will recognize and honor page delimiters. This means that when you scroll through a document, VM will display text only up to the next page delimiter. Text after the delimiter will be hidden until you type another SPC, at which point the text preceding the delimiter will become hidden. The Emacs variable page-delimiter determines what VM will consider to be a page delimiter.

You can “unread” a message (so to speak) by typing U (vm-unread-message, also called vm-mark-message-unread). The current message will be marked unread. Conversely, you can mark an unread message as read by typing . (vm-mark-message-read). Setting the variable vm-move-after-reading will cause vm to move to the next undeleted message after marking the current message as read.

As you read messages, you might want to flag important messages so that you can come back to them later. You can do so by typing ! (vm-toggle-flag-message). You can also turn off the flag on a flagged message by typing ! again. In the Summary display, the flagged messages are highlighted using the vm-summary-high-priority-face. (See predefined summary faces.)

Sometimes you will receive messages that contain lines that are too long to fit on your screen without wrapping. Setting vm-word-wrap-paragraphs to t will cause VM to use the longlines.el library by Grossjohann, Schroeder and Yidong to carry out word wrapping. You must have this library installed somewhere on your load-path. Another way to deal with the problem is to use the visual-line-mode in Emacs 23. You can activate it automatically for viewing messages by adding the function turn-on-visual-line-mode to the vm-presentation-mode-hook.

If you are unable to use either of these solutions, then you can use Emacs’s paragraph filling facility. If you set vm-fill-paragraphs-containing-long-lines to a positive numeric value N, VM will call fill-paragraph on all paragraphs that contain lines spanning N columns or more. You can also set this variable to the symbol window-width, in which case the width of the current window is used the limiting width beyond which paragraph filling is invoked. As with other things that VM does for presentation purposes, this does not change the message contents. VM copies the message contents to a “presentation” buffer before altering them. The fill column that VM uses is controlled by vm-paragraph-fill-column. Unlike the Emacs variable fill-column, this variable is not buffer-local by default.

3.3 Reading MIME Messages

MIME is a set of extensions to the standard Internet message format that allows reliable transmission of arbitrary data including images, audio and video, as well as ordinary text in different languages. By default, VM will recognize MIME encoded messages and display them as specified by the various MIME standards specifications. This can be turned off by setting the variable vm-display-using-mime to nil and VM will then display MIME messages as plain text messages.

At its most basic level, MIME is a set of transfer encodings used to ensure error free transport, and a set of content types. VM understands the two standard MIME transport encodings, Quoted-Printable and BASE64, and will decode messages that use them as necessary. VM will also try to recognize and decode messages using the UNIX uuencode encoding system. While this is not an official MIME transfer encoding and never will be, enough old mailers still use it that it is worthwhile to attempt to decode it.

• Viewing MIME messages
• Operating on MIME attachments
• Internal display of MIME attachments
• HTML display
• External display of MIME attachments
• Displaying inline images in messages
• MIME type conversion
• MIME character sets
• MIME multipart/alternative
• MIME multipart/related
• Inferring MIME types
• Reading Secure MIME Messages

(setq vm-mime-auto-displayed-content-types '("text" "image/jpeg"))

(setq vm-mime-auto-displayed-content-type-exceptions '("text/html"))

(setq vm-mime-internal-content-types '("text" "message" "image/jpeg"))

(TYPE FUNCTION ARG ARG ... )

(TYPE PROGRAM ARG ARG ... )

(TYPE COMMAND-LINE)

(setq vm-mime-external-content-types-alist
      '(
         ("text/html"   browse-url-of-file)
         ("image/gif"   "xv")
         ("image/jpeg"  "xv")
         ("video/mpeg"  "mpeg_play")
         ("video"       w32-shell-execute "open")
       )
)

((TYPE . SUFFIX) ...)

(setq vm-mime-attachment-auto-suffix-alist
      '(
        ("image/jpeg"           .       ".jpg")
        ("image/gif"            .       ".gif")
        ("image/png"            .       ".png")
        ("text"                 .       ".txt")
       )
)

(add-to-list 'vm-mime-internal-content-types "image/tiff")

( (START-TYPE END-TYPE COMMAND-LINE ) ... )

(setq vm-mime-type-converter-alist
       '(
         ("image/jpeg"  "image/gif"     "jpeg2gif")
         ("text/html"   "text/plain"    "striptags")
        )
)

(add-to-list 'vm-mime-default-face-charsets "Windows-1251")
(add-to-list 'vm-mime-default-face-charsets "Windows-1252")
(add-to-list 'vm-mime-default-face-charsets "Windows-1257")

 ( ( START-CHARSET END-CHARSET COMMAND-LINE ) ... )

(setq vm-mime-charset-converter-alist
      '(
         ("utf-8" "iso-2022-jp" "iconv -f utf-8 -t iso-2022-jp -c")
       )
)

(setq vm-mime-charset-font-alist
  '(
    ("iso-8859-5" . "-*-*-medium-r-normal-*-16-160-72-72-c-80-iso8859-5")
   )
)

  (favorite TYPE ...)

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem

cat key.pem cert.pem > key-cert.pem

(("joe@example.com" "~/.ssl/key-cert.pem"))

4.1 Mail Sending Options

As already mentioned, VM uses Emacs Mail Mode in the Gnu Emacs Manual for sending email. Therefore, Mail Mode options should be set to configure the mail sending. The extra options provided by VM are described below.

The variable vm-mail-auto-save-directory can be used to specify the directory in which the message composition buffers should be auto-saved. If it is nil, the vm-folder-directory is used for auto-saving.

When a mail composition buffer is created, VM initializes it with header lines that you can fill in. The From header is usually standard and contains your email address. You can have VM fill it in for you automatically by setting the variable vm-mail-header-from. (It is nil by default.)

The variable vm-mail-use-sender-address, if set to t, asks VM to fill in the To header from the sender’s name and address of the current message. This has effect only when vm-mail-from-folder is invoked from a VM folder. When vm-mail is invoked, possibly from other buffers, the To headers is unfilled. (Some people tend to use vm-reply to get this effect, but that is a bad practice because it also tags the new message as a reply to an older message.)

The variable vm-mail-mode-hidden-headers can be used to hide some of the header lines from the mail composition buffer. By default, the headers “References” and “X-Mailer” are hidden.

Additional header lines are created by VM before the composed message is sent. The variable vm-mail-header-insert-date can be set to t (which is the default value) asking VM to insert a Date header into a message before it is sent. You should set it to nil if you would like to insert a Date header yourself. The variable vm-mail-header-insert-message-id asks VM to insert a Message-ID header before sending the message. The variable vm-mail-reorder-message-headers asks VM to reorder the message headers into a particular order before sending. The order is determined by the variable vm-mail-header-order.

4.2 Sending MIME Messages

To use VM’s MIME composition features, you must have vm-send-using-mime set to a non-nil value. With MIME composition enabled, VM will allow you to add file attachments to your composition and will analyze your message when you send it and MIME encode it as necessary.

4.3 Sending Secure MIME Messages

VM supports sending S/MIME messages utilizing the ‘smime.el’ package included in Emacs. Sending signed, secure, or signed secure messages is essentially no different from sending any other message, except that, sometime before hitting send (C-c C-c), you would use one of the following functions

• vm-smime-sign-message
• vm-smime-encrypt-message
• vm-smime-sign-encrypt-message

These can be used in any combination, but note that VM, when instructed to both encrypt and sign, will always sign before encrypting. Also, signing and encrypting (at present) is only supported for the entire message, including any attachments and text parts.

The functions above only set flags, the actual job of signing and encrypting is done at the very last stage before sending the message. There are several ways VM can choose which certificates to use in encrypting a message. The preferred way is specified via the variable vm-smime-get-recipient-certificate-method. At present, the options are one of ’ask or ’links.

• ’ask

  Tells VM to prompt the user for all certificates, after entering one the user will be prompted to add more or just send.

• ’links

  This method tells VM that recipient certificates are stored under smime-certificate-directory using the recipients email address as a file name, e.g.

  ~/.ssl/jow@example.com -> joes-cert.pem
  

  This doesn’t require prompting the user unless a particular recipient address could not be associated with a file, in which case the user will be promoted to provide a replacement.

If errors occur during signing or encrypting or thereafter, VM will stop sending the message and whatever steps were completed before will not be repeated. For example, if you request a message to be signed and encrypted, and signing was successful but encryption failed due to a bad certificate file for one of the recipients, then the message will remain signed and the sign flag will be turned off. You can then fix the problem and send the message again with the assurance that it won’t be double-signed but it will be encrypted.

4.4 Replying

VM has special commands that make it easy to reply to a message. When a reply command is invoked, VM fills in the subject and recipient headers for you, since it is apparent whom the message should be sent to and what the subject should be. There is an old convention of prepending the string ‘Re: ’ to the subject of replies if the string isn’t present already. You can customize the string to be prepended in this way by setting the variable vm-reply-subject-prefix. Its value should be a string to prepend to the subject of replies, if the string isn’t present already. A nil value means don’t prepend anything to the subject (this is the default). In any case you can edit any of the message headers manually, if you wish.

VM also helps you cite material from the message to which you are replying, by providing included text as a feature of some of the commands. Included text is a copy of the message being replied to with some prefix to each line so that the included text can be distinguished from the text of the reply. By default, the prefix string is ‘> ’. This can be customized via the variable vm-included-text-prefix.

The reply commands are:

r (vm-reply)

Replies to the author of the current message.

R (vm-reply-include-text)

Replies to the author of the current message and provides included text.

f (vm-followup)

Replies to the all recipients of the current message.

F (vm-followup-include-text)

Replies to the all recipients of the current message and provides included text.

vm-mail-to-sender

Writes a message to the sender of the current message. (This is similar to vm-reply but meant for writing a message about a new subject.)

These commands all accept a numeric prefix argument n, which if present, causes VM to reply to the next (or previous if the argument is negative) n-1 messages as well as the current message. Also, all the reply commands set the “replied” attribute of the messages to which you are responding, but only when the reply is actually sent. The reply commands can also be applied to marked messages. (see Marking Messages.)

If you are one of multiple recipients of a message and you use f and F, your address will be included in the recipients of the reply. You can avoid this by judicious use of the variable vm-reply-ignored-addresses. Its value should be a list of regular expressions that match addresses that VM should automatically remove from the recipient headers of replies. The default value is nil, which means that no addresses are removed.

The variable vm-in-reply-to-format specifies the format of the In-Reply-To header that is inserted into the header section of the reply buffer. Like vm-included-text-attribution-format, vm-in-reply-to-format should be a string similar to that of vm-summary-format. A nil value causes the In-Reply-To header to be omitted. If the format includes elements that can contain non-ASCII characters, then ‘In-Reply-To’ should be added to vm-mime-encode-headers-regexp.

The recipient headers generated for reply messages are created by copying the appropriate headers from the message to which you are replying. This includes any full name information, comments, etc. in these headers. If the variable vm-strip-reply-headers is non-nil, the recipient headers will be stripped of all information except the actual addresses.

• Included text
• Filling included text
• Alternative methods to include text
• Options

[DELETED ATTACHMENT mary.jpg, image/jpeg]

[ATTACHMENT mary.jpg, image/jpeg]

4.5 Forwarding Messages

VM has four commands to forward messages: z (vm-forward-message), Z (vm-forward-message-plain), @ (vm-send-digest) and B (vm-resend-message).

• Forwarding
• Digests
• Resending

4.6 Saving copies of sent mail

You can save copies of outgoing mail messages in ’sent’ folders by adding an ‘FCC:’ header line to the composed message. The value of the header should be either the full path name of a mail folder on the file system or the maildrop specification of a folder on an IMAP server. If you use IMAP folders for saving sent mail, you should also add the function vm-imap-save-composition to the mail-mode’s mail-send-hook variable.

If you have multiple IMAP accounts, you might wish to save copies of your replies separately in each IMAP account. This can be done by adding an ‘IMAP-FCC:’ header line. The value of the header field should be a plain folder name on the “current” IMAP account, e.g., ‘Sent’. The “current” IMAP account will be determined by the IMAP folder from which you start composing the new message (which is called the “parent folder” for you composition). If the parent folder is not an IMAP folder or if there is no parent folder, then the message copy will be saved in a folder on vm-imap-default-account.

The variable vm-do-fcc-before-mime-encode allows you save the fcc copy to the sent folder before mime-encoding the message. This is useful if you want to save an unencrypted version of the message or avoid saving attachments. However, the character coding of the sent folder should be chosen carefully to allow proper storage of the messages.

5.1 Marking Messages

VM provides a way to mark selected messages so that subsequent operations can be applied to them. This is similar to marking in other parts of Emacs, e.g., see (emacs)Dired Marks, but arguably more powerful. For example, one can mark all messages from a particular sender and save them to a folder, or mark all messages with a particular subject and print them. One can also mark messages by searching for particular strings in their text.

To mark the current message, type M M (vm-mark-message). If you give a numeric prefix argument n, the next n-1 messages will be marked as well. A negative prefix argument means mark the previous n-1. An asterisk (‘*’) will appear to the right of the message numbers of all marked messages in the summary window.

To remove a mark from the current message, use M U (vm-unmark-message). Prefix arguments work as with vm-mark-message.

Use M m to mark all messages in the current folder; M u removes marks from all messages.

Other marking commands:

M C (vm-mark-messages-by-selector)

Mark all messages matching a virtual selector. See Virtual Folders.

M c (vm-unmark-messages-by-selector)

Unmark all messages matching a virtual selector.

M X (vm-mark-messages-by-virtual-folder)

Mark all messages matching the selectors of a virtual folder. See Virtual Folders.

M x (vm-unmark-messages-by-virtual-folder)

Unmark all messages matching the selectors of a virtual folder.

M T (vm-mark-thread-subtree)

Mark all messages in the thread tree rooted at current message. See Threading.

M t (vm-unmark-thread-subtree)

Unmark all messages in the thread tree rooted at current message.

M S (vm-mark-same-subject)

Mark messages with the same subject as the current message.

M s (vm-unmark-same-subject)

Unmark messages with the same subject as the current message.

M A (vm-mark-same-author)

Mark messages with the same author as the current message.

M a (vm-unmark-same-author)

Unmark messages with the same author as the current message.

While the above commands can be used in any VM buffer, the following commands can be used in a Summary buffer to mark or unmark a region of message summary lines.

M R (vm-mark-summary-region)

Mark all messages in the current region in a Summary buffer

M r (vm-unmark-summary-region)

Unmark all messages in the current region in a Summary buffer

To apply a VM command to all marked messages you must prefix it with the key sequence M N (vm-next-command-uses-marks). The next VM command will apply to all marked messages, provided the command can be applied to such messages in a meaningful and useful way. Unfortunately, as of this writing, this mechanism works only if the next command invoked is a keyboard command. Commands invoked by M-x are unable to access the marked messages. So, to invoke a complex command, you might temporarily bind it to an unused key, e.g.,

M-x local-set-key C vm-forward-message-all-headers
M N C

forwards marked messages with all headers included.

It is possible to use marking to execute operations on message threads. For example, the sequence of key strokes:

MuMTMNsMu

saves a thread of messages. However, there are faster methods to operate on message threads. See Thread Operations.

10.1 Threading

A thread is a group of messages that are either related by subject or that have a common ancestor. Threading is the process of determining the relationship between such messages and displaying them so that those relationships are evident.

To enable and disable threading, type C-t (vm-toggle-threads-display). You will find that, in the summary buffer, all related messages are grouped together and the subject titles are indented to show hierarchical relationships.

Message relationships are discovered by examining the References, In-Reply-To, and Subject headers. The first two headers are more reliable sources of information but not all mailers provide them. Therefore, all messages with similar Subject headers are also grouped into threads. If you don’t want VM to use Subject headers for threading, set the variable vm-thread-using-subject to nil.

Unlike in previous versions of VM, threading is not a form of sorting. You can sort threads by the usual sort keys and the sort order will apply to at least the root messages of threads. Sorting threads by subject, for instance, can be a quick way to find threads with similar subject lines. Sorting them by date would sort them chronologically according to when the threads were initiated. Sorting them by activity is a variant of the chronological order where the dates of latest activity are given prominence instead of the dates of the initial messages.

Normally, thread-based grouping applies to entire threads as well as all their subthreads. You can block subthread grouping by setting the variable vm-sort-subthreads to nil. In that case, all the internal messages of the threads are sorted by the chosen sort order, e.g., by date, author etc. instead of being grouped into subthreads.

The value of the variable vm-move-messages-physically applies to threading just as it applies to sorting.

12.1 Summary Format

The variable vm-summary-format controls the format of each message’s summary. Its value should be a string. This string should contain printf-like “%” conversion specifiers which substitute information about the message into the final summary.

Recognized specifiers are:

a

attribute indicators (always four characters wide)
The first char is ‘D’, ‘N’, ‘U’ or ‘!’ for deleted, new, unread and flagged messages respectively, and ‘ ’ if none of the conditions apply.
The second char is ‘F’, ‘W’ or ‘ ’ for filed (saved) or written messages.
The third char is ‘R’, ‘Z’ or ‘ ’ for messages replied to, and forwarded messages.
The fourth char is ‘E’ if the message has been edited, ‘ ’ otherwise.

A

longer version of attributes indicators (seven characters wide).

The first char is ‘D’, ‘N’, ‘U’ or ‘!’ for deleted, new, unread and flagged messages respectively, and ‘ ’ if none of the conditions apply.
The second is ‘R’ or ‘ ’, for message replied to.
The third is ‘Z’ or ‘ ’, for messages forwarded.
The fourth is ‘B’ or ‘ ’, for messages redistributed.
The fifth is ‘F’ or ‘ ’, for messages filed.
The sixth is ‘W’ or ‘ ’, for messages written.
The seventh is ‘e’ or ‘ ’, for messages that have been edited.

b

shorter version of the attribute indicators (one character wide).
‘D’, ‘N’, ‘U’ or ‘!’ for deleted, new, unread and flagged messages respectively, and ‘ ’ if none of the conditions apply.

*

message mark, ‘*’ if the message is marked, ‘ ’ otherwise

p

indicator for a postponed message: P or the string customized by vm-summary-postponed-indicator

P

indicator for a message with attachments: $ or the string customized via vm-summary-attachment-indicator

I

thread indentation

n

message number

i

message ID

c

number of characters in message (ignoring headers)

S

human readable size of the message

l

number of lines in message (ignoring headers)

d

numeric day of month message sent

w

day of the week message sent

m

month message sent

M

numeric month message sent (January = 1)

y

year message sent

h

hour:min:sec message sent

H

hour:min message sent

z

timezone of date when the message was sent

f

author’s address

F

author’s full name (same as f if full name not found)

t

email addresses of the addressees of the message (listed in the “To” header), in a comma-separated list

T

full names of the addressees of the message (listed in the “To” header), in a comma-separated list

r

addresses of the recipients of the message (listed in the “To” or “Cc” headers), in a comma-separated list

R

full names of the recipients of the message, in a comma-separated list (or their email addresses if full names are not given)

s

message subject

L

labels (as a comma list)

U

user defined specifier. The next character in the format string should be a letter. VM will call the function vm-summary-function-<letter> (e.g. vm-summary-function-A for “%UA”) in the folder buffer with the message being summarized bracketed by (point-min) and (point-max). The function will be passed a message struct as an argument. The function should return a string, which VM will insert into the summary as it would for information from any other summary specifier.

(

starts a group, terminated by %). Useful for specifying the field width and precision for the concatenation of group of format specifiers. Example: \"%.35(%I%s%)\" specifies a maximum display width of 35 characters for the concatenation of the thread indentation and the subject.

)

ends a group.

Use “%%” to get a single “%”.

A numeric field width may be specified between the “%” and the specifier; this causes right justification of the substituted string. A negative field width causes left justification. The field width may be followed by a “.” and a number specifying the maximum allowed length of the substituted string. If the string is longer than this value, it is truncated.

If you save copies of all your outbound messages in a folder and later visit that folder, the ‘%F’ format specifier will normally display your own name. If you would rather see the recipient addresses in this case, set the variable vm-summary-uninteresting-senders. This variable’s value, if non-nil, should be a regular expression that matches addresses that you don’t consider interesting enough to appear in the summary. When such senders would be displayed by the ‘%F’ or ‘%f’ summary format specifiers VM will substitute the value of vm-summary-recipient-marker (default "To: ") followed by what would be shown by the ‘%T’ and ‘%t’ specifiers respectively.

If the recipients of the message are also “uninteresting” in this way, then VM will substitute the value of vm-summary-principal-marker (default "For: ") followed by the name or address in the ‘Reply-To’ header.

(For compatibility with older versions, the variable vm-summary-recipient-marker is also referred to by its old name, vm-summary-uninteresting-senders-arrow.)

The summary format need not be one line per message but it must end with a newline, otherwise the message pointer will not be displayed correctly in the summary window.

Summary lines are pre-computed and cached in the folder buffer. If you change the vm-summary-format, you need to force the cache to be updated. You can do this by the commandvm-fix-my-summary.

Every folder can have its own summary format. The format is written into the folder and saved on the disk. When you visit the folder again, you can reuse the saved summary format. Set the variable vm-restore-saved-summary-format to t to achieve this effect.

12.2 Threaded Summaries

When message threading is enabled (see Threading), you will find that the Summary buffer has all related messages are grouped together and the subject titles are indented to show hierarchical relationships. Parent messages are displayed before their children and children are indented by a default two spaces to the right. The amount of indentation per level is controlled by the variable vm-summary-thread-indent-level. The default is two spaces. The variable vm-summary-maximum-thread-indentation says how many levels should be displayed via indentation. The default is 20.

If you want VM to always display summaries using threads, you should set the default value of the variable vm-summary-show-threads non-nil in your VM init file. Example:

(setq-default vm-summary-show-threads t)

Do not use setq, as this will only set the value of the variable in a single buffer. Once you’ve started VM you should not change the value of this variable. Rather you should use C-t to control the thread display. See Threading.

• Manual control of thread indentation

12.3 Thread Folding

A new feature in VM version 8.2 is that of “folding” message threads in the summary window. This feature allows you to collapse all the messages in a thread into a single line of the summary window, so that you can see a more compact summary of the folder.

Thread folding is enabled by setting the variable vm-summary-enable-thread-folding to a non-nil value. The summary window then has a folding indicator in the first column: with - for threads that are expanded and + for threads that are collapsed. The command T (vm-toggle-thread) allows you to expand a collapsed thread or collapse an expanded thread. The commands vm-expand-thread and vm-collapse-thread implement the more specific versions of the function.

When threads are folded, not all messages in the threads are hidden. New messages that are yet unread continue to be visible. Which messages remain visible in folded threads is controlled by the variable vm-summary-visible, whose value must be a list of VM selectors in the same format as those in vm-virtual-folder-alist. See Virtual Folders.

The variable vm-summary-thread-folding-on-motion allows a more automatic expansion/collapsing of threads. If the variable is set to a non-nil value, then the usual motion commands N and P (vm-next-message-no-skip and vm-previous-message-no-skip) cause the threads to be expanded or collapsed as needed when you move into or out of threads.

The variable vm-summary-show-thread-count allows a more elaborate display of the thread information in the summary window. If it is set to non-nil then the message number field of the summary line includes a count of the messages in its thread, in the format N+C where N is the message number and C is the message count in the thread. This takes up 3 extra columns in the summary lines. Set the variable to nil to obtain the more standard format of the summary.

When thread folding is enabled, the Summary window starts out with all the threads folded. You can expand all the threads in the folder using the command E (vm-expand-all-threads). The command C (vm-collapse-all-threads) does the reverse.

12.4 Thread Operations

When you have thread-folding enabled, you can execute VM operations such as saving and deleting messages on entire threads. To obtain this functionality, set the variable vm-enable-thread-operations to a non-nil value in your vm-init-file. Setting it to ‘t’ enables thread operations unconditionally. Setting it to the symbol ‘ask’ allows a confirmation dialog before a thread operation is invoked. You can use the command vm-toggle-thread-operations in a running VM session to enable or disable thread operations.

As an example, doing an s (vm-save-message) operation on an ordinary message saves just the single message. However, if thread operations are enabled and you invoke s on the root message of a collapsed thread, then the entire thread is saved. The same effect can be obtained using message marking. See Marking Messages. The following sequence of key strokes can achieve the effect of saving an entire thread:

MuMTMNsMu

However, the thread-operation is simpler and more convenient.

All operations that can be sensibly invoked on multiple messages extend to thread operations in this way. They include deleting, undeleting, marking, unmarking, forwarding, saving/deleting attachments etc. Replying to messages cannot be invoked as a thread operation. This is to avoid accidentally sending replies to unintended recipients.

The thread operations can give rise to surprising behavior. Even though it appears that an operation was invoked on a single message, it actually applies to all the messages in a thread. So, care and practice are warranted before you enable thread operations unconditionally. A safer option is to set ‘vm-enable-thread-operations’ to ‘ask’. In that case, VM asks for confirmation every time an operation is applicable to all the messages in a collapsed thread. You can override the confirmation dialog by giving a prefix argument ‘C-u’ to your operation.

12.5 Summary Faces

By default, the summary of a folder is shown in a black-and-white window with plain text. This is suitable for terminal mode Emacs users. The variable vm-summary-highlight-face, which is set to the standard Emacs bold face by default, is used to highlight the currently selected message. You can set the variable to any other face, or to nil if you wan to turn off highlighting.

You can turn on more elaborate faces support, suitable for color graphics terminals, by setting the variable vm-summary-enable-faces to t in your vm-init-file. You can also run M-x vm-summary-faces-mode in the middle of a VM session to turn on summary faces. Then VM decorates the summary lines with different faces based on the attributes of the message. See Faces in the GNU Emacs Manual, for basic information on faces. The predefined faces used to highlight the summary window are listed below. It is possible for you to change the definitions of these faces in your vm-init-file as well as to define new faces of your own.

The variable vm-summary-faces-alist defines a list of condition-action pairs for decorating the summary with faces. It has the following form:

( ((SELECTOR [ARG ...])    vm-summary-FACE)
  ... )

The first element of each pair is a VM selector in the same format as used for vm-virtual-folder-alist. See Virtual Folders. The second element is a face name of the form vm-summary-FACE where FACE is one of the face types listed below. The first condition satisfied by the message wins, and the face listed there is used to decorate its summary line.

The faces vm-summary-selected, vm-summary-collapsed and vm-summary-expanded are special. They are added to the face specified by vm-summary-faces-alist instead of replacing it. This allows VM to add highlighting for the selected message and the collapsed/expanded thread roots, without scrubbing the natural face determined by the message attributes.

The variable vm-mouse-track-summary controls whether summary entries are highlighted when the mouse pointer passes over them. The highlighting is done using the standard Emacs highlight face.

Hiding summary lines

The command vm-summary-faces-hide allows you to hide the summary lines of messages with a particular face type. By default, it hides messages with the deleted face type. By invoking it with a prefix argument, you can specify other face types that you might like to hide. (Note that deleted face type does not necessarily mean deleted messages. Whatever messages satisfy the condition associated with the vm-summary-deleted-face in vm-summary-faces-alist will be hidden.)

Predefined summary faces

• vm-summary-high-priority: Messages that are flagged or have other priority headers.
• vm-summary-low-priority: Messages that might be of low priority, by user-defined criteria.
• vm-summary-deleted: Deleted messages.
• vm-summary-new: New messages that have arrived during the session.
• vm-summary-unread: Messages that have not been read.
• vm-summary-marked: Messages currently marked.
• vm-summary-replied: Messages for which a reply has been sent.
• vm-summary-saved: Messages saved to a folder on disk. (Subsumes the earlier categories filed and written.)
• vm-summary-forwarded: Messages forwarded to other recipients. (Subsumes the earlier category redistributed.)
• vm-summary-edited: Messages edited after receipt.
• vm-summary-outgoing: Messages sent by you.
• vm-summary-default: Messages not matching any of the above criteria.
• vm-summary-collapsed: Root messages of threads that are collapsed.
• vm-summary-expanded: Root messages of threads that are expanded.
• vm-summary-selected: Message that is currently selected.

13.1 Search Folders

The command vm-create-search-folder (bound to V C) lets you interactively create a virtual folder from the messages of the current folder, using exactly one selector to choose the messages. If you type V C header RET greeting, VM will create a folder containing only those messages that contain the string ‘greeting’ in one of its headers. See Virtual Selectors, for virtual selectors you can use for this purpose. The variants vm-create-search-folder-other-frame and vm-create-search-folder-other-window provide similar functionality.

The command vm-create-search-folder-of-threads (bound to V T) lets you create a virtual folder in the same way, but consisting of entire message threads. If a message thread contains any message matching the given selector then it is included in the virtual folder. For instance, if you type V T author RET Peter then all threads containing a message authored by ‘Peter’ will be included in the virtual folder.

The command vm-apply-virtual-folder (bound to V X) tries the selectors of a defined virtual folder against the messages of the current folder and creates a virtual folder containing the matching messages.

The commands vm-create-virtual-folder-same-subject (bound to V S), vm-create-virtual-folder-same-author (bound to V A) and vm-create-virtual-folder-same-recipient (bound to V R) create virtual folders containing all the messages in the current folder with the same subject, author or recipient as the current message. There are also short-cut key bindings for a number of frequently used selectors:

V a (vm-create-author-virtual-folder)

V r (vm-create-author-or-recipient-virtual-folder)

V s (vm-create-subject-virtual-folder)

V t (vm-create-text-virtual-folder)

V d (vm-create-date-virtual-folder)

V l (vm-create-label-virtual-folder)

V ! (vm-create-flagged-virtual-folder)

V n (vm-create-new-virtual-folder)

V u (vm-create-unseen-virtual-folder)

When you run vm-quit on a search folder, the currently selected message in the search folder becomes the current message in the underlying folder. So, you can use the search folder facility to search for particular messages. For example, if you knew that one of the messages with the subject ‘greeting’ had a hotel offer and you wanted to find it, you can first create a search folder of messages with subject ‘greeting’, browse through them to find the message that had the hotel offer, and then quit the search folder. VM will return you to the copy of the same message in the original folder. (You can go back to the previously viewed message in the original folder by doing vm-goto-mesasge-last-seen. To inhibit changing the current message in the original message entirely, quit the search folder using vm-quit-no-change.)

Search folders also form an efficient way to search for some string in the text of messages. The key binding V t (vm-create-text-virtual-folder) can be used to find all messages with the string. This is more efficient than the vm-isearch-forward command (see Navigating) because it only searches in the text part of message bodies, not inside MIME attachments.

13.2 Defined Virtual Folders

A defined virtual folder is defined by its name, the folders that it contains and its selectors. The variable vm-virtual-folder-alist is a list of the definitions of all such virtual folders. You can visit a virtual folder listed in vm-virtual-folder-alist with the vm-visit-virtual-folder (V V) command.

Each virtual folder definition should have the following form:

(VIRTUAL-FOLDER-NAME
  ( (FOLDER ...)
    (SELECTOR [ARG ...]) ... )
  ... )

VIRTUAL-FOLDER-NAME is the name of the virtual folder being defined. This is the name by which you and VM will refer to this folder.

FOLDER should be the specification of a real folder: a file path for a local folder or a maildrop specification for a POP/IMAP folder. There may be more than one FOLDER listed, the SELECTORs within that sublist will apply to them all. If FOLDER is a directory, VM will assume this to mean that all the folders in that directory should be searched.

The SELECTOR is a Lisp symbol that tells VM how to decide whether a message should be included in the virtual folder. (See below for a complete list of the possible selectors.) Some SELECTORs require an argument ARG; unless otherwise noted, ARG may be omitted. When several selectors are listed, messages matching any one of them are included.

The text selector provides a particularly effective way to search for strings in messages. It is better than the vm-isearch-forward/backward functions because it avoids searching inside encoded attachments, hence faster.

Here is an example that you may find useful as a template for creating virtual folder definitions.

(setq vm-virtual-folder-alist
   '(
     ;; start virtual folder definition
     ("virtual-folder-name"
      (("/path/to/folder" "/path/to/folder2")
       (header "foo")
       (header "bar")
      )
      (("/path/to/folder3" "/path/to/folder4")
       (and (header "baz") (header "woof"))
      )
     )
     ;; end of virtual folder definition
   )
)

When you visit a defined virtual folder, all the underlying folders that it depends on will be visited automatically. Likewise, when you quit the virtual folder, all the underlying folders that were purposely visited as part of the virtual folder will be closed automatically. But any other underlying folders that you might have previously visited for independent reasons will remain open.

• Virtual Selectors

13.3 Working with Virtual Folders

Once you’ve visited a virtual folder most VM commands work as they do in a normal folder. There are exceptions. If you use S (vm-save-folder), the folder save command will be invoked on each real folder in turn. Similarly if you use g (vm-get-new-mail) in a virtual folder, mail is retrieved from the spool files associated with each of the real folders. If any of the retrieved messages are matched by the virtual folder’s selectors, they will be added to the virtual folder.

These commands will signal an error when invoked in a virtual folder:

    vm-save-buffer
    vm-write-file
    vm-change-folder-type
    vm-expunge-imap-messages
    vm-expunge-pop-messages

Normally messages in a virtual folder share attributes with the underlying real messages. For example, if you delete a message in a virtual folder, it is also flagged as deleted in the real folder. If you then run vm-expunge-folder in the virtual folder, the deleted message is expunged from the virtual folder as well as the real folder. Labels are shared between virtual and real messages. However virtual folders have their own set of message marks.

To make virtual folders not share message attributes with real folders by default, set the variable vm-virtual-mirror to nil. This should be done in your VM init file and you should use setq-default, as this variable is automatically local to all buffers.

(setq-default vm-virtual-mirror nil)

If you want to change virtual mirror status of a particular virtual folder, use the command vm-toggle-virtual-mirror (bound to V M). If the virtual folder is currently sharing attributes with real folders, it will no longer be. If it is not sharing attributes with the underlying folders then it will be.

13.4 vm-avirtual Package

The ‘vm-avirtual’ add-on package created by Robert Widhopf-Fenk provides various automatic operations based on virtual selectors. These facilities are only partially documented.

The command M-x vm-virtual-omit-message (bound to V O in version 8) will omit a message from a virtual folder, irrespective of whether it satisfies the definition of the virtual folder. The command M-x vm-virtual-update-folders (bound to V U in version 8) will add the current message to all visited virtual folders that it logically belongs to. This is useful for adding newly arrived messages or newly marked messages to virtual folders.

The command M-x vm-virtual-check-selector-interactive (bound to V ? in version 8) allows you to test a selector, i.e., a virtual folder definition, interactively by applying it to the current message. With a prefix argument, it will print diagnostic information in a separate buffer. This feature is useful because virtual folder selectors can get quite complicated and it is important to make sure that they work correctly.

The vm-avirtual packages allows you to use virtual selectors to carry out automatic deletion of messages (e.g., for spam) and for automatic saving of messages to folders.

• Automatic deletion
• Automatic saving

((VIRTUAL-FOLDER-NAME . FOLDER)
 ... )

15.1 Frame Configuration

VM has a set of variables that let you specify when VM creates frames and what attributes the new frames will have.

If vm-frame-per-folder is set non-nil, when you visit a folder, VM will create a new frame and display that folder in the new frame. When you quit the folder, VM will delete the frame.

If vm-frame-per-summary is set non-nil, the vm-summarize command will create a new frame in which to display a folder’s summary buffer. This works best if a full-screen window configuration has been assigned to the vm-summarize command. When you quit the folder or kill the summary, VM will delete the frame.

Setting vm-frame-per-composition non-nil causes VM to create a new frame for the composition buffer when you run any of VM’s message composition commands. E.g. vm-reply-include-text, vm-mail-from-folder, vm-mail, vm-forward-message. When you finish editing the composition and send it, or when you kill the composition buffer, the frame will be deleted.

The variable vm-frame-per-edit, if non-nil, tells VM to create a new frame when the vm-edit-message command is run. When you finish editing the message, or abort the edit, the frame will be deleted.

If vm-frame-per-help is set non-nil, VM will create a new frame to display any help buffer produced by the vm-help command.

If vm-frame-per-completion is set non-nil, VM will create a new frame on mouse initiated completing reads. A mouse initiated completing read occurs when you invoke a VM command using the mouse, either with a menu or a toolbar button. That command must then prompt you for information, and there must be a limited set of valid responses. If these conditions are met and vm-frame-per-completion’s value is non-nil, VM will create a new frame containing a list of responses that you can select with the mouse.

When VM is deciding whether to create a new frame, it checks other existing frames to see if a buffer that it wants to display in a frame is already being displayed somewhere. If so, then VM will not create a new frame. If you don’t want VM to search other frames, set the variable vm-search-other-frames to nil. VM will still search the currently selected frame and will not create a new frame if the buffer that it wants to display is visible there.

The variable vm-frame-parameter-alist allows you to specify the frame parameters for newly created frames.

The value of vm-frame-parameter-alist should be of this form

((SYMBOL PARAMLIST) (SYMBOL2 PARAMLIST2) ...)

SYMBOL must be one of “completion”, “composition”, “edit”, “folder”, “primary-folder” or “summary”. It specifies the type of frame that the following PARAMLIST applies to.

completion

specifies parameters for frames that display lists of choices generated by a mouse-initiated completing read. (See vm-frame-per-completion.)

composition

specifies parameters for mail composition frames.

edit

specifies parameters for message edit frames (e.g. created by vm-edit-message-other-frame)

folder

specifies parameters for frames created by ‘vm’ and the vm-visit- commands.

primary-folder

specifies parameters for the frame created by running vm without any arguments.

summary

specifies parameters for frames that display a summary buffer (e.g. created by vm-summarize-other-frame)

PARAMLIST is a list of pairs as described in the documentation for the function make-frame.

15.2 Window Configuration

Window configurations allow you to specify how the windows within a frame should look for a particular command or class of commands. Each command can have a configuration associated with it and you can also associate a configuration with command classes like “reading-message” or “composing-message”. To setup a window configuration, first use Emacs’ window management commands (split-window, enlarge-window, etc.) to make the windows in the frame look the way you want. Then use the switch-to-buffer command to put the buffers you want to see into the windows. Next type W S, which invokes the vm-save-window-configuration command. Type the name of the command or class of commands to which you want the configuration to apply. Nearly all VM commands can be entered here. Valid classes are:

    default
    startup
    quitting
    reading-message
    composing-message
    marking-message
    searching-message

When a VM command is executed, window configurations are searched for as follows. First, a command specific configuration is searched for. If one is found, it is used. Next a class configuration is searched for. Not all commands are in command classes. Message composition commands are in the “composing-message” class. All the vm-quit* commands are in the “quitting” class. All the VM commands that set and clear message marks are in the “marking-message” class, and so on. If such a class configuration is found it is used. If no matching class configuration is found, the “default” class configuration is used, if it is defined.

Note that when a window configuration is saved the selected window at that time will be the selected window when that window configuration is used. So if you prefer for the cursor to be in a particular window, make sure you invoke vm-save-window-configuration window from that window. Remember that you can invoke the command with M-x if VM’s normal key map is not in effect.

To delete a window configuration, use W D which is bound to vm-delete-window-configuration. You will be prompted for the name of the configuration to delete.

To see what an existing configuration looks like, type W W which invokes vm-apply-window-configuration.

VM saves information about your window configurations in the file named by the variable vm-window-configuration-file. The default location of the configuration file is "~/.vm.windows". Do not make vm-window-configuration-file point to the same location as vm-init-file, as the window configuration save commands will then overwrite the content of your init file.

20.1 Configuration of VM

• Hints on email environment configuration

M-: (find-file (vm-stunnel-configuration-file))

21.1 Reading messages

• Shrunken headers

(setq vm-enable-addons (cons 'shrunken-headers vm-enable-addons))

21.2 Saving messages and attachments

• Auto saving attachments

21.3 Printing messages

22.1 VM-Pine

Sometimes, you might want to interrupt the composing of a message and continue it later. This is called postponing. The add-on called ‘vm-pine’ provides this functionality.

In a message composition buffer, the command C-c C-d (vm-postpone-composition) postpones the current composition. The postponed message is stored in the folder specified in vm-postponed-folder. (The default is a folder called “postponed”). When called with a prefix argument, vm-postpone-composition will ask you for the folder to save the draft to. You might also save it to your inbox in this way.

You can continue composing the postponed messages by visiting vm-postponed-folder, selecting a message and running M-x vm-continue-postponed-message. This constructs a new message composition buffer by copying the text from the VM Presentation buffer. It also converts any MIME buttons into attachment buttons, which will be encoded as valid MIME attachments when the message is sent. Unfortunately, any attachments that are displayed inline in the Presentation buffer will not be encoded. This is a limitation of this package.

When you continue composition of a postponed message and send it, its previous draft is still retained in the postponed folder. To expunge such drafts automatically set vm-auto-expunge-postponed-folder to t in your VM configuration file.

(This add-on was provided by Robert Fenk.)

22.2 VMPC: Programmable customization of message composition

VMPC (also called “VM-Pcrisis”) is a powerful customization package that allows you to automatically customize message compositions based on their parent messages. The most immediate application of this package is for composing replies where, for instance, you might want to set the “From:” header of the outgoing message to be the same as the email address at which you received the message. This matters clearly if you have multiple email accounts.

VMPC is based on condition-action rules. You define a variable vmpc-conditions to contain a collection of named conditions that you can test for in the parent message, and a variable vmpc-actions to contain a collection of name actions that you can perform on the outgoing message. These take the form:

(set-variable 'vmpc-conditions
              '(("condition-name1" condition)
                ("condition-name2" condition)
                ...))
(set-variable 'vmpc-actions
              '(("action-name1" action...)
                ("action-name2" action...)
                ...))

Then, you can set the following variables to contain a collection of condition-action rules, each of which is of the form:

(CONDITION-NAME ACTION-NAME1 ACTION-NAME2...)

vmpc-default-rules ¶

Condition-action rules for composing messages based on a parent message, such as replying, forwarding, resending and mailing (see vm-mail-from-folder).

There are also specialized variables vmpc-reply-rules, vmpc-forward-rules, vmpc-resend-rules and vmpc-mail-rules, which can override the general default rules in vmpc-default-rules.

vmpc-newmail-rules

Condition-action rules for new message compositions with no parent message. (see vm-mail).

vmpc-automorph-rules

Condition-action rules for message compositions based on their own content (called “automorphing”).

The conditions are typically checked in the “parent folder” of a mail composition, which may be the message you are responding to, forwarding, resending etc. VMPC provides a collection of useful condition-checking functions. Others can be defined as needed.

vmpc-header-match

This condition checks if a header field of the message matches a regular expression pattern. For example, the condition

(vmpc-header-match "To\\|Cc" (regexp-quote "me@myisp.net"))

checks if either the “To” or “Cc” header contains the pattern me@myisp.net.

vmpc-only-from-match

This is similar to vmpc-header-match, but assumes that the header field contains email addresses, and matches every one of the email addresses against the regular expression pattern. For example, the condition

(vmpc-only-from-match "To\\|Cc" (regexp-quote "@mycompany.com"))

if every email address in the “To” and “Cc” headers is at mycompany.com.

vmpc-body-match

This condition checks if the body of the message contains the given regular expression pattern.

vmpc-folder-match

This condition checks if the name of the folder contains the given regular expression pattern.

vmpc-folder-account-match

This condition checks if the POP/IMAP account of the folder contains the given regular expression pattern.

vmpc-check-virtual-selector

(This function is provided by the vm-avirtual package.) This condition checks if the message matches a given virtual selector.

The conditions are just normal functions. So, you can combine them with connectives like and, or and not, and add other functions that are defined in Emacs or VM or new functions of your own.

The actions are typically executed in the mail composition buffer for the message you are composing.

vmpc-substitute-header

This action substitutes a specified header field of the outgoing message with a given string. For example, the action

(vmpc-substitute-header "From" "me@myisp.net")

sets the “From” header of the outgoing message to me@myisp.net.

vmpc-add-header

This action adds a specified header field to the outgoing message with a given string. If the header field already exists, nothing is done.

vmpc-insert-header

This action appends a given string to a specified header field of the outgoing message.

vmpc-delete-header

This action deletes a specified header field of the outgoing message with a given string. Either the contents of the header field or the header itself can be deleted.

vmpc-signature

The action (vmpc-signature "signature-file") inserts the signature from signature-file. If there is already a signature in the outgoing message, then it replaces with the new signature.

vmpc-pre-signature

This action is similar to vmpc-signature, but inserts the new signature at the top, above the message body.

27.1 Folder Internals

VM stores mail folders in the Unix ‘mbox’ format (in all its variants). Internal to Emacs, the mbox is loaded into a text buffer (the Folder buffer) and individual messages are identified by remembering markers into the text buffer. See Message Internals.

The Unix mbox format is described in the RFC 4155 specification of the Internet Engineering Task Force. The mail folder is a text file consisting of a sequence of messages, with each message consisting of a series of headers followed by a message body. The beginning of each message is delineated by a separator line starting with the string “From ” and the end of the message by a blank line. The leading separator line in VM folder is of the form “From VM ...” where the “...” records the time at which VM first saw the message. The format of the individual messages is as per the RFC 2822 specification, except that Line-Feed characters may be used to delineate the end of lines in the "Unix" format.

Three variants of the mbox format are recognized by VM, called From_, BellFrom_ and From_with-Content-Length. In a From_ type mbox, every message has a leading and trailing separator line, as indicated above. In a BellFrom_ type mbox, the trailing separator line can be missing. (This is so that the mbox’s from the old System V format can be handled.) In a From_with-Content-Length type mbox, the From separator line stores the length of the message. So, no trailing separator line is required.

In addition to these mbox formats, VM also handles the MMDF format and the Emacs Rmail’s Babyl format. The variable vm-folder-type stores the type of the folder being used.

To every message, VM adds a header with the field name “X-VM-v5-Data:” and stores in it the information about the message it wishes to remember between sessions.

The first message of the VM folder file contains additional headers used by VM for remembering information between sessions.

• X-VM-Bookmark. This header stores the position of the cursor, as a message number, in effect when VM saved the folder. Upon revisiting the folder, VM attempts to put the cursor back at this position.
• X-VM-Last-Modified. The date and time at which the folder was last modified.
• X-VM-Message-Order. This header lists the order in which the messages should be listed.
• X-VM-Labels. This header lists the message labels that have been used in the folder.
• X-VM-VHeader. This header lists the values of vm-visible-headers and vm-invisible-header-regexp that were in effect when the folder was saved. The messages in the folder would have their headers arranged according to these variables.
• X-VM-Summary-Format. This header stores the format string for the summary lines.
• X-VM-POP-Retrieved. This header lists all the messages that have been retrieved from POP servers together with the identifying information for the POP servers. VM refrains from retrieving these messages again in future in order to avoid duplication.
• X-VM-IMAP-Retrieved. This header lists messages that have been retrieved from IMAP servers together with their identifying information on the IMAP servers (UID and UIDVALIDITY). VM refrains from retrieving these messages again in future in order to avoid duplication. (For local folders, this lists all the retrieved messages except those known to be expunged on the server. For IMAP folders, it does not list all the retrieved messages because they are normally the same as those on the server. Only the messages locally expunged in the cache folder but not known to be expunged on the server are listed. In the normal cases, the variable is just nil in IMAP folders.)

• Folder variables

27.2 Message Internals

The format of the mail messages is as described in RFC 822. The message bodies can be in the MIME format, as described in RFC 2045, 2046 and 2047. See See RFC compliance.

The message data structure is a vector containing various pieces of data about the message, some of which is permanent and some that is calculated during a VM session. The data is organized into four sub-vectors:

• Location data (0). This data about the location of the various parts of the message in the Folder buffer is calculated after a folder is loaded and parsed.
• Soft data (1). This vector contains other calculated data about the message that is specific to a VM session.
• Attributes (2). All the hard-wired message attributes are stored in this vector.
• Cached Data (3). Calculated data that is cached for each message.
• Mirror Data (4). Extra data shared by virtual messages if vm-virtual-mirror is non-nil.

The attributes vector and cached data vector are stored in the folder on disk as the X-VM-v5-Data header of the first message.

Location data

This vector holds the data about the location of the various parts of the message in the folder buffer. Every folder buffer or folder-like buffer (such as a Presentation buffer) has variables that contain message data structures. The location data is normally expected to refer to locations in that very buffer. However, this condition is not actually required. (See below.)

• start (0). Marker for the starting position of the message, at which a leading separator line begins.
• headers (1). Marker for the position in the buffer where the headers of the message start.
• vheaders (2). Marker for the position in the buffer where the visible headers of the message start. (The headers are rearranged in such a way that all the visible headers are towards the end of the headers region.)
• text (3). Marker for the position in the buffer where the text of the message starts.
• text-end (4). Marker for the position in the buffer where the text of the message ends.
• end (5). Marker for the position in the buffer where the message ends.

Unfortunately, in the current versions of VM, the folder buffer to which the location data point is not itself part of this vector. This information is inferred from the context (which makes the code brittle). The Folder buffer of the message can be obtained from the soft data vector but the location data could also point to a Presentation buffer.

Soft data

This vector contains other calculated data about the message that is specific to a VM session.

• number (0). The message number as an integer.
• padded-number (1). The message number as a padded string.
• mark (2). Flag that indicates if the message has been marked (via vm-mark-message).
• su-start (3). The position in the Summary buffer where the summary line of the message starts.
• su-end (4). The position in the Summary buffer where the summary line of the message ends.
• real-message-sym (5). If the message is in a virtual folder, then its corresponding “real message” is the underlying message in another folder which is described by a message data structure similar to the current one. The real message data structures are represented by uninterned symbols written as “<<>>”. This field stores the symbol representing the real message of the current message. If the current message is a real message then this field contains its own symbol. The use of symbols for this purpose avoids the possibility of circular data structures.
• mirrored-message-sym (21). This is similar to the real-message-sym, except that it points to the message that this message directly mirrors (as a virtual message). If we follow the “mirrored-message” links in succession we should eventually reach the “real-message”.
• reverse-link-sym (6). Reference to the previous message in the message list, also represented by an uninterned symbol written as “<–”.
• message-type (7). A symbol indicating the type of the message according to its folder type, one of BellFrom_, From_ and From_-with-Content-Length.
• message-id-number (8). A number that uniquely identifies the message within a VM session.
• buffer (9). The Folder buffer of the message. (Messages in Presentation buffers also have this field set to the corresponding Folder buffer.)
• thread-indentation (10). Indentation level of the message in its message thread.
• thread-indentation-offset (22). Indentation added by the user for the message, which is used in addition to the thread-indentation. This is not “cached” data and should not be discarded.
• thread-list (11). List of symbols from vm-thread-obarray that give this message’s lineage.
• thread-subtree (20). List of messages that form the subtree under this message in a threaded summary display.
• babyl-frob-flag (12).
• saved-virtual-attributes (13). Saved attributes if the message switched from unmirrored to mirrored.
• saved-virtual-mirror-data (14). Saved mirror data, if the message was switched from unmirrored to mirrored.
• virtual-summary (15). Summary for unmirrored virtual message.
• mime-layout (16). MIME layout information; types, ids, positions, etc of all MIME entities. (See below.)
• mime-encoded-header-flag (17). Flag that indicates if the headers of the message are MIME encoded.
• su-summary-mouse-track-overlay (18). The overlay on the summary of this message used for selection by mouse.
• message-access-method (19). The access-method to be used for the message, inherited from its real folder.

Attributes

All the hard-wired message attributes are stored in this vector. They also get saved as part of the X-VM-v5-Data header field when the folder is saved to disk.

• new-flag (0). Flag to indicate if the message is “new”.
• unread-flag (1). Flag to indicate if the message is unread.
• deleted-flag (2). Flag to indicate if the message has been deleted.
• filed-flag (3). Flag to indicate if the message has been filed.
• replied-flag (4). Flag to indicate if the message has been replied to.
• written-flag (5). Flag to indicate if the message has been saved.
• forwarded-flag (6). Flag to indicate if the message has been forwarded.
• edited-flag (7). Flag to indicate if the message has been edited.
• redistributed-flag (8). Flag to indicate if the message has been redistributed.
• flagged-flag (9). Flag to indicate if the message has been “flagged” as important.
• folded-flag (10). Flag to indicate whether the summary of the subthread rooted at this message has been “folded”, i.e., hidden from view.
• watched-flag (11). Flag that says that the user wants to “watch” this thread. There are no functions that use this at present.
• ignored-flag (12). Flag that says that the user wants to ignore this thread. There are no functions that use this at present.
• read-receipt-flag (13). Flag that says that the sender of this message wishes to receive a read-receipt. There are no functions that use this at present.
• read-receipt-sent-flag (14). Flag that says that a read-receipt has been sent for this message. There are no functions that use this at present.
• attachments-flag (15). Flag that says that this message has attachments. There are no functions that use this at present.
• thread-root-flag (16). Flag that says that this message should be regarded as the root of a message thread, even if its “parent” and “references” headers say otherwise. This field is not used at present.

Cached Data

The vector is meant for data that is cached for each message and stored on the disk as part of the X-VM-v5-Data header field. Cached data is present in other parts of the message or its headers and, so can be freely discarded and recalculated. That is history.

Over the years, this vector has also accumulated a number of fields that are not “cached” data in this sense. Some fields contain hard data that is not available elsewhere, such as the ID’s of external messages on mail servers. It also contains data provided by the user which should be preserved across VM sessions.

Some fields contain information from message headers. The header fields can have MIME-encoded words in them. The strings stored in the cached-data vector, however, are MIME-decoded versions of the header fields. So, when they are written to disk, they should be re-encoded because only MIME-encoded text can appear in mail folders. To facilitate this, they are given text properties that store the names of the original character sets used in the header fields. This allows the strings to be quickly re-encoded for storage on disk.

• byte-count (0). The size of the message in bytes.
• weekday, monthday, month, year, hour, zone (1-6). Data indicating the date of the message.
• decoded-full-name (7). The full name of the author of the message. This is a MIME-decoded string with text properties.
• decoded-from (8). The email address of the author of the message. This is a MIME-decoded string with text properties.
• message-id (9). The unique id of the message.
• line-count (10). The number of lines in the message.
• decoded-subject (11). The subject string of the message. This is a MIME-decoded string with text properties.
• vheaders-regexp (12). A regular expression that can be used to find the start of the visible headers. The headers must have been already ordered so that the visible headers are at the bottom of the headers section.
• decoded-to (13). The email addresses of the addressees of the message (listed in the “To” header) in a comma separated string. This is a MIME-decoded string with text properties.
• decoded-to-names (14). The full names of the addressees in a comma separated string. Addresses are used if full names are not available. This is a MIME-decoded string with text properties.
• month-number (15). Numeric month of the sent date.
• sortable-datestring (16). The date string of the “date” of the message for sorting purposes (either the sent date or the delivery date, depending on the value of vm-sort-messages-by-delivery-date).
• decoded-sortable-subject (17). The subject string of the message for sorting purposes. (Prefixes such as “re:” are removed and subject tags of mailing lists might also be removed.) This is a MIME-decoded string with text properties.
• decoded-tokenized-summary (18). A tokenized summary for the message, from which the actual summary line can be quickly calculated. This is a list containing tokens, such as number and thread-indent, as well as MIME-decoded strings with text properties.
• parent (19). The message ID of the parent of the message in its thread.
• references (20). Message IDs listed in the References header of the message.
• body-to-be-retrieved (22). Flag that indicates whether the body of the message has not been retrieved from the mail server.
• body-to-be-discarded (21). Flag that indicates whether they body of the message should be discarded before the folder is saved. (This is used in conjunction with the body-to-be-retrieved above.)
• pop-uidl (23). The UIDL id of the message on the POP server.
• imap-uid (23). The UID of the message on the IMAP server.
• imap-uid-validity (24). The UIDVALIDITY value of the message on the IMAP server.
• spam-score (25). The spam score of the message.
• headers-to-be-retrieved (26). Flag that indicates whether the headers of the message have not been retrieved from the mail server (for external messages). This is not “cached” data and should not be discarded. This field is unused at present.
• headers-to-be-discarded (27). Flag that indicates whether the headers of the message should be discarded before the folder is saved (for external messages). This is not “cached” data and should not be discarded. This field is unused at present.
• decoded-summary-subject (28). Subject of the message as it appears in the summary line of the message. (This optionally omits the subject tags added by mailing lists.)
• declared-parent (29). The message ID of the parent of the message, as declared by the user. This may not be present in the headers of the message. So, it is not “cached” data and should not be discarded. This field is not used at present.
• declared-duplicates (30). List of message ID’s that the user declared as being duplicates of this message. The duplicate copies may not be present in the folder, but they should be taken into account in calculating threads. This is not “cached” data and should not be discarded. This field is not used at present.
• d-weekday, d-monthday, d-month, d-year, d-hour, d-zone (31-36). Data indicating the delivery date of the message. These fields are not used at present.
• decoded-reply-to-name, decoded-reply-to (37-38). The full name and the email address in the ‘Reply-To’ header of the message (called the “principal” of the message.)
• decoded-to-cc-name, decoded-to-cc (39-40). The full names and the email addresses in the ‘To’ and ‘Cc’ headers of the message (called the “recipients” of the message.)

Mirror Data

Extra data shared by virtual messages if vm-virtual-mirror is non-nil.

• edit-buffer (0). If the message is being edited, this is the buffer being used.
• virtual-messages-sym (1). List of virtual messages mirroring the current real message, represented by an uninterned symbol written as “<v>”.
• stuff-flag (2). Flag to indicates if the attribute changes have been “stuffed” into the folder buffer.
• labels (3). List of labels attached to the message.
• label-string (4). The string of labels attached to the message.
• attribute-modflag (5). Flag to indicate if the attributes of the message have been modified since the last save.

• MIME layout
• Cross-buffer sharing of data
• RFC compliance

27.3 Summary Internals

Generating a summary is quite a time-consuming operation. VM uses a variety of tricks to speed up the generation of summaries.

The format of the summary lines is specified in the variable vm-summary-line-format. The information that needs to go into the summary lines is divided into two classes:

• Information that is fixed for each message. Examples include the subject, author and other header information.
• Information that is variable during a VM session. Examples include the message number and thread indentation.

A tokenized summary line is a list whose elements can be strings, representing fixed information in a message, and tokens, representing variable information. VM calculates a tokenized summary line for each message and caches it in the cached-data vector. The following forms of tokens are used in tokenized summary lines:

• number. Stands for the message number in the linear order of the summary.
• mark. Stands for an indicator of message mark (whether the message is marked at present).
• thread-indent. Stands for the indentation to be used for the message’s summary depending on its position in the message thread.
• group-begin, group-end. Brackets used to denote groups of items that might have particular formatting constraints.

The function vm-tokenized-summary-insert converts a tokenized summary line into a string and inserts it in the summary buffer. The minibuffer message “Generating summary...” is used to show the progress of generating summary lines from tokenized summaries.

Buffer local variables in each Folder buffer responsible for maintaining summary information:

• vm-summary-pointer. The message selected by the cursor in the Summary window.
• vm-summary-redo-start-point. A pointer into the vm-message-list indicating the first message for which the summary line must be redisplayed. All the messages from here on are assumed to require a summary redisplay. The assumption is usually valid because the message numbers of all the succeeding messages might have changed. But, if message numbers are not included in the summary lines, then this results in unnecessary work.
• vm-messages-needing-summary-update. The list of messages for which summary lines must be redisplayed. Messages are included in this list by calling the function vm-mark-for-summary-update.
• vm-numbering-redo-start-point. A pointer into vm-message-list indicating the first message whose message number needs to be recalculated. vm-numbering-redo-end-point. A pointer into vm-message-list indicating the last message whose message number needs to be recalculated.

The beginning and the ending positions of each message summary line are stored in the message’s soft data vector. see Message Internals. The positions within the summary line have text-properties set, which give the data about the message:

• vm-message. The message struct for which this line is a summary.

27.4 Threading Internals

Message threads required for threaded summaries are calculated using message ID’s, which are unique when the message was originally composed. However, VM may need to deal with multiple copies of the same message received via possibly different routes. So, message ID’s are not unique for messages inside VM.

Messages composed as replies generally have an “In-Reply-To” header. The message mentioned in this header is referred to as the parent of the message. In addition, messages also arrive with a “References” header which lists all the ancestors of the message, with the oldest message being listed first. The last message listed in the “References” header is the direct parent of message. It is important to keep in mind that all the messages listed in the “References” header may not be present in the VM folder.

Thread trees are constructed using the “In-Reply-To” headers and “References” headers. Jamie Zawinski has done a good analysis of the information contained in these headers which can be found on the web. VM’s threading algorithm is currently based on these ideas. These trees are called reference-based threads.

In addition, VM also allows threads to be built using the subject headers via the option vm-thread-using-subject. Subject-based threading is used in addition to reference-based threading. So, in a subject-based thread, the root message would be the oldest message with that subject and, below it, would be reference-based threads all of which share the same subject. The roots of these reference-based threads are referred to as the “members” of the subject thread. Subject threading is only one level deep, whereas reference threading can be arbitrarily deep.

Threads are built using two hash tables vm-thread-obarray and vm-thread-subject-obarray. The former keeps track of the thread obtained by following parent and reference chains. The latter keeps track of messages with the “same subject”. To prevent messages from jumping from one thread to another within the same VM session, the subject used is not the message’s own subject, but rather the subject of the oldest message in the thread. This subject is retained even if the oldest message is expunged.

The message ID’s are interned in vm-thread-obarray and the following information is stored for each message ID:

• messages: The list of messages that carry this message ID in the folder. There could be none, if we only know this message from its appearance in other “References” headers.
• message: The “canonical” message with this message ID. It is typically the first message encountered by VM with this message ID. If there are no messages with this ID, then the field is nil.
• date: The date of the message.
• parent: The interned message ID of the parent of this message. (The folder may or may not contain a message with this ID.) If there is no parent, then this is nil
• children: The interned message ID’s of all the children of this message. (The folder may or may not contain messages with these ID’s.)
• youngest-date: The date of the youngest message in the thread, among all the messages present in the folder.
• oldest-date: The date of the oldest message in the thread, among the messages present in the folder.
• oldest-subject: The subject of the oldest message in the thread, among the messages present in the folder.

The vm-thread-subject-obarray interns each subject string found in the folder and maps it to a vector containing the following elements:

• id-sym: The interned message ID of what is likely to be the root of the thread, which is, at any rate, the oldest message with this subject.
• date: The date of the root message.
• members: A list of interned message ID’s for the “members” of the subject thread, which are messages without any reference-based ancestors. The root message represented by id-sym is not included as a member.
• messages: The list of all the messages in the folder that have this subject.

Building threads involves calculating all the data stored with the vm-thread-obarray and vm-thread-subject-obarray. These two collections of data are calculated in sequence, because the subject threads are based on the reference threads.

After the threads are built, the thread-list, thread-indentation and the thread-subtree fields of the Soft data vector are calculated as needed on demand and cached. (See Soft data vector.) These fields cannot be calculated without building threads first.

When new messages are assimilated, they are added to the threads that might have been already built, and the thread-related fields in the Soft data vector are erased so that they will be recalculated. The thread-subtree field is erased for all the ancestors of the assimilated message. The thread-list and thread-indentation fields are erased for all the descendants of the assimilated message.

Before messages in the folder are expunged, they are unthreaded. This involves removing them from their respective thread trees. It also involves the erasure of the thread-subtree field of all their ancestors and the thread-list and thread-indentation fields of the descendants.

• Error handling

27.5 Sorting Internals

Sorting of messages in VM is carried out using the Emacs built-in sorting function, which is generic in the comparison operation to be used for sorting. The required comparison operation is expressed as a sequence of basic comparison operations such as comparison by date, by author, by subject etc. The dynamic variable vm-key-functions is bound to a list of comparison functions before calling the Emacs sort function.

The function vm-sort-compare-xxxxxx uses the functions listed in vm-key-functions to do the overall comparison. It compares the given messages using the key functions in sequence. If the first key function decides one of the messages to precede the other, then the comparison is over. If the messages are found to be equivalent according to the first key function then the second key function is tried and, if they are still equivalent, then the next key function is tried and so on. This is called the lexicographic combination of the given key functions.

Sorting by threads is special. When messages are to be sorted by threads, all the messages belonging to a thread should appear together. The required effect is achieved by using vm-sort-compare-thread as the first key function in the sequence. This function checks to see if the two messages belonging to the same thread. If they do then the farthest ancestors of the two messages that share the same parent are returned so that the remaining comparison operations can be applied to these ancestors. The rationale is that these ancestors are the roots of the thread subtrees that the two messages belong to. So, the relative ordering of the messages should be the same as the relative ordering of these ancestors. If the two messages belong to different threads then the thread roots of the two messages are returned, again with the same rationale.

Threaded summaries can be sorted by any key, e.g., by author (full-name). It is most common to sort them by “activity,” i.e., the order of the most recent message in the thread or subthread. Sorting them by “date” means using the date of the root message of the thread or subthread.

27.6 IMAP Server Interaction

When IMAP servers are used as mail spools (or “drop boxes”) for local folders, VM opens a session with the IMAP server each time it is asked to get new mail. These sessions are closed immediately after the downloading is completed.

When VM is used to handle IMAP folders, sessions are created with the server each time a synchronization is performed (for reading as well as saving). A separate session is created for each IMAP folder visited in VM. If, in addition, the IMAP folders have external messages, VM keeps an active session with the server (separately for each IMAP folder), which is used to fetch messages on demand.

When an IMAP session is inactive for a certain period, IMAP server is likely to forcibly close it. To ensure that an IMAP session is active when VM tries to talk to the server, it first checks that the session is active. (This can be disabled by setting vm-imap-ensure-active-sessions.) If the server has forcibly closed the connection, it would not respond, and Emacs networking code times out after a certain period. During this process, VM will appear to “hang.” In reality, it is waiting for the Emacs networking code to come back with a response.

27.7 User Interaction

For each mail folder, VM creates three kinds of buffers in Emacs: the Folder buffer, the Presentation buffer and the Summary buffer. All three types of buffers have the same user interface as far as possible: the same key bindings, menu bars, tool bars and also the same commands. The functions implementing the commands must therefore work irrespective which of the three buffers they are invoked in. This makes VM quite different from most Emacs modes.

VM stores the identity of the Folder buffer in a buffer-local variable vm-mail-buffer in each of the other types of buffers. Conversely, each Folder buffer uses buffer-local variables vm-summary-buffer and vm-presentation-buffer to store the identity of the other buffers.

Whenever a VM command is invoked by the user, VM calls a function called vm-select-folder-buffer-and-validate, which sets the current-buffer to the Folder buffer. It also stores the identity of the buffer with the user’s focus in a global variable called vm-user-interaction-buffer. Thus, at every point during the command execution, VM has knowledge of all the buffers involved as well as the buffer in which the command execution was initiated.

[More to be filled in on vm-display etc.]

• Menus

27.8 Coding Systems

A Coding System is a way of encoding characters as bit patterns. see Coding System Basics in Emacs Lisp manual. US-ASCII is a coding system for English. Other coding systems are used to encode the various languages of the world, e.g., ‘iso-latin-1’ (also called ‘iso-8859-1’ or simply ‘latin-1’) for Western European languages, and hebrew-iso-8bit (also called ‘iso-8858-8’) for Hebrew. In addition to these standard coding systems, Emacs uses its own internal coding system for characters, which can encode all character sets currently in existence. But the internal coding system can vary between different versions of Emacs.

MIME messages specify the character set that their content is in, in the ‘Content-Type’ header. In reality, the “character set” is a reference to a coding system, which has been used to encode the characters in the particular character set as bit patterns. However, the name that Emacs uses to refer to a coding system is often different from the MIME character set name. The correspondence between the two is defined via a property called mime-charset for each implemented coding system inside Emacs. For example, the mime-charset property of ‘iso-latin-1’ is ‘iso-8859-1’, that of ‘hebrew-iso-8bit’ is ‘iso-8859-8’. The Emacs function coding-system-get can be used to extract the mime-charset property of an Emacs coding system. VM stores all the known coding systems and the corresponding MIME charsets in its internal variables vm-mime-mule-coding-to-charset-alist and vm-mime-mule-charset-to-coding-alist.

VM uses this information to decode the content to the Emacs internal coding system. This is done using the function decode-coding-region. Conversely, VM encodes the outgoing messages into the default or chosen MIME character set using the function encode-coding-region.

The headers of email messages can only be in US-ASCII. So header fields in other character sets are encoded using either base-64 or quoted-printable encoding (which yield ASCII strings) and annotated with the name of the original character set. Such annotations look like =?charset?B?. They can apply to individual words or sequences of words appearing the in the headers. Note that the annotation ?B? signifies a base-64 encoding of the byte stream. Similarly the annotation ?Q? is be used to denote the quoted-printable encoding. VM decodes such strings using the function decode-coding-string. Conversely, the headers of outgoing messages are encoded using encode-coding-string.

When header lines are MIME-decoded from the original character set into the Emacs internal coding, the original character set is still remembered as a text property of the strings. The strings in the X-VM-v5-Data header have these text properties and, when the header is written to the disk, these strings are converted back into their original MIME encodings.

27.9 Message Display

VM displays messages in a “Presentation buffer” separate from the Folder buffer. This is done in two stages: Preview and Show.

The previewing is done by a function called vm-present-current-message. It creates a Presentation buffer if it is not present already, makes a copy of the message text in the Presentation buffer and carries out any MIME decoding that may be necessary. And, then, depending on the value of vm-preview-lines, it narrows the buffer to show a selected portion of the message.

The full message display is done by vm-show-current-message. It does nothing more than removing the narrowing done by vm-present-current-message.

Prior to version 8.2.0, it was possible to see plain text messages directly in the Folder buffer. That mode of operation is now obsolete. For uniformity, VM assumes that the Presentation buffer is always used for displaying the message content.

27.10 MIME Display

The MIME layout of a message is stored in the mime-layout field of the Soft data vector of the message. (See MIME layout.) The MIME layout is in general a tree structure of “MIME parts”. The function vm-decode-mime-layout is responsible for traversing the tree structure at each MIME part and displaying it appropriately.

The function vm-decode-mime-layout goes through the following sequence of decisions:

1. If the MIME part is a multipart type, then the subparts are displayed as needed. If it is a single part, it proceeds as follows.
2. If the MIME part should not be displayed automatically, it is displayed as a button. (An automatically displayed MIME type is one listed in vm-mime-auto-displayed-content-types but not listed in the corresponding exceptions.)
3. If the MIME part should be displayed internally and VM is able to do so, then it is displayed internally. (An internally displayed MIME type is one listed in vm-mime-internal-content-types but not listed in the corresponding exceptions.)
4. Otherwise, the MIME part is displayed externally. An external viewer is found from vm-mime-external-content-types-alist and it is invoked to display the MIME part.

MIME parts of type ‘message/external-body’ need special treatment. If they are not asked to be auto-displayed, then they are displayed as buttons, but the button caption may use information from the child part (the actual object that is in the external-body) such as its type and description. If a message/external-body part is asked to be auto-displayed, then the child part is fetched from the external source and stored in an internal buffer. It may be auto-displayed if it is appropriate to do so, or shown in turn as a button.

MIME buttons are displayed as regions of text displaying button labels. In addition, they have an overlay/extent placed on them, which has a number of properties associated with it:

• vm-button. Always t.
• vm-mime-layout. Gives the layout of the MIME part.
• vm-mime-function. The function that carries out the action represented by pressing the button.
• vm-mime-disposable. Set to true if the button should be removed when it is replaced by the MIME object.
• face. Set to the value of vm-mime-button-face.
• local-map (FSF Emacs) or keymap (XEmacs). Set to a keymap that includes vm-mime-reader-map, binding the $ keys.

27.11 MIME Composition

A MIME message is composed just like a normal message. When objects are attached using commands like vm-attach-file, attachment buttons are created in the message composition buffer. An attachment button is a region of text that looks like:

[Attachment mary.jpeg, image/jpeg]

Various text properties are associated with an attachment button, allowing it to be turned into an actual attachment when the message is sent.

The representation of the attachment buttons differs in GNU Emacs and XEmacs. In GNU Emacs, the region of text is given text properties that represent the metadata about the object. In XEmacs, the region of text is given an extent, which is then given properties representing the metadata. The reason for the different representations is that in GNU Emacs, only text properties are preserved under killing and yanking.

The following properties are defined for attachment buttons:

• vm-mime-object. The object denoting the MIME attachment. It is either
  • a string denoting a file name,
  • a buffer containing the file to be attached,
  • a list of the form (buffer, start, end, filename) indicating a region in a buffer, typically the Folder buffer, or
  • t indicating that the attachment is another MIME object in a VM folder.

  In the last case, the vm-mime-layout property describes the rest of the metadata.

• vm-mime-type. A string denoting the MIME type of the object. (Note that it is a single string, unlike the type component of a MIME layout.)
• vm-mime-parameters. A list of strings denoting the parameters of the MIME type.
• vm-mime-description. A string for the MIME description of the object.
• vm-mime-disposition. A list describing the MIME disposition.
• vm-mime-encoded. A boolean indicating whether the object has MIME headers.
• vm-mime-encoding. The MIME encoding used, if it is already encoded.
• vm-mime-forward-local-refs. Whether or not references to local external-body objects should be forwarded as is.
• fontified. Standard text property.
• duplicable. Set to t in XEmacs allowing the extent to be preserved under killing and yanking.
• front-nonsticky and rear-nonsticky. Standard stickiness of text properties in GNU Emacs.