Top ¶

Spool Files ¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

POP Spool Files ¶

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

VM retrieves the messages while you carry on reading: the fetch is started and Emacs comes straight back to you, the messages arrive a bunch at a time, and the mode line says how far it has got. One fetch brings in everything waiting, however large the mailbox.

You can say how large a message VM will fetch at all. If you set vm-pop-max-message-size to a positive numeric value, VM leaves a message larger than that on the server and says how large it was and what the limit is; raise the limit and the next vm-get-new-mail brings it in. In earlier releases VM asked, message by message, whether to retrieve it.

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

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

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

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

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

Here is an example:

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

IMAP Spool Files ¶

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

VM retrieves the messages while you carry on reading: the fetch is started and Emacs comes straight back to you, the messages arrive a bunch at a time, and the mode line says how far it has got. One fetch brings in everything waiting, however large the mailbox.

You can say how large a message VM will fetch at all. If you set vm-imap-max-message-size to a positive numeric value, VM will not retrieve messages larger than this size from a maildrop. Each one is left on the server, and VM says how large it was and what the limit is; raise the limit and the next vm-get-new-mail brings it in. In earlier releases VM asked, message by message, whether to retrieve it, delete it or leave it, and showed you its headers to decide by.

This is about a maildrop, fetched into a local folder, which cannot go back to the server for a body later. In an IMAP folder an oversize message is retrieved as its headers alone where vm-enable-external-messages includes imap, and its body is fetched when you read it.

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

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

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

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

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

Here is an example:

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

• Multiple access to IMAP spool files

Index Files ¶

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

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

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

Folder types ¶

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

VM’s own format has not changed: a folder is a From_ folder (VM’s mbox, see VM's mbox) unless you ask for something else. mboxcl2 is opt-in, and the way to ask is the folder’s name: an extension of ‘.mboxcl2’. Nothing converts a folder of yours behind you, and neither VM nor an FCC: nor a cache turns From_ into mboxcl2 on its own.

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

Every message in an mboxcl2 folder carries a Content-Length header, which is how the end of a message is found.

• VM writes one on every message it puts in such a folder.
• VM refuses to read a message that has none, and names it. A folder written by a mailer that omits the header is one VM will not open.
• A length that is wrong rather than missing gives no sign of it. The folder opens, VM falling back on a search for the next separator, while anything that believes the header, which is what the format is for, reads the wrong bytes.

vm-change-folder-type is the repair for both. Converting a folder to the type it already claims recomputes every length.

• A prefix argument asks for a file and converts it on disk without visiting it, which is the only way in when the folder cannot be read.
• Two prefix arguments write the result to a file you name and leave the original alone, for comparing the two before parting with either.
• Either way the folder as it was is kept in a backup file, named as Emacs names one when saving a buffer. Changing a visited folder’s type keeps a backup too.
• The folder’s own type is among the types offered, so the repair can be run on a folder that is open in front of you.

A folder that does not exist yet has no contents to examine, so a name can say what it is instead. vm-folder-type-by-extension-alist matches the file name’s extension against folder types, and out of the box a folder whose name ends in ‘.mboxcl2’ is created as one, which is what a name like 2026-08.out.mboxcl2 was already trying to say. ‘.mbox’ is From_, which is what everything outside VM means by an mbox file.

A name settles the question for an existing folder too, but only between From_ and mboxcl2: those are the same folder but for the Content-Length header, so a folder that looks like one gives no evidence either way. A folder called .mboxcl2 is read as mboxcl2 whether or not it has the headers yet, and one that does not have them is refused with the message above, which is how you find out, rather than VM reading it as a From_ folder and saying nothing. A folder’s own contents win where they decide the question: a BABYL file called old.mboxcl2 is read as BABYL.

An extension, and not a pattern over the name. A pattern can be written so that it matches nothing, and it does so silently, since a rule that matches nothing is a rule that does nothing. It can also be written so that it claims every folder in a directory, which for a directory holding one mboxcl2 folder and nine From_ ones is nine folders VM then refuses to read. Neither can be said in an extension.

What it costs: a folder that cannot be renamed cannot be typed by its name. A primary inbox called INBOX is the case, and the answer for one is vm-default-folder-type, or a name with the extension on it.

Why mboxcl2: it will not corrupt your mail ¶

In a From_ folder the end of a message is the next line that begins “From ”. Nothing but the structure of the line says so, and mail contains such lines: a message that quotes another message, a digest, a mailing list footer, a base64 attachment that happens to wrap that way. The answer every mailer uses, VM included, is to alter the mail to protect the format, turning such a line in a body into “>From ”. That works, and it costs you the original: a line that already read “>From ” is indistinguishable from one that was quoted, and nobody unquotes on reading, so what you read back is close to what arrived rather than what arrived. VM quotes a narrower set of lines than most, which is a difference of degree and not of kind. See VM's mbox.

An mboxcl2 folder records the length of each body instead, so the boundary is arithmetic rather than a guess, and no body needs altering. Two things follow:

• A message is stored exactly as it came, byte for byte. A signature still verifies, an attachment still has its original bytes, and a message containing a From_ line cannot split a folder in two.
• Finding the end of a message costs a count rather than a search, which for a folder of tens of thousands of messages is the difference between reading the lengths and scanning the file.

The cost is that the header must be right. A missing one is refused and named; a wrong one is worse, because the folder opens. See Folder types above for the repair. This is why VM writes its own files (the caches below) in mboxcl2 and can be relied on to have got the lengths right, while a folder some other mailer wrote is only as good as that mailer.

How VM’s mbox differs from other mbox files ¶

There is no standard for mbox, and mailers do not all do the same thing. VM’s From_ folders differ from what other mailers write in several ways. None of it matters while VM alone reads and writes the folder; all of it matters when another program reads that folder, appends to it, or wrote it in the first place.

VM quotes fewer ‘From ’ lines than other mailers. ¶

VM quotes, as every mailer does: a body line that would be taken for a separator gets ‘>’ put in front of it. What differs is which lines. Most mailers quote every body line beginning ‘From ’. VM quotes only a line that begins ‘From ’ and ends in a digit, as a date does: in regular expression terms, ‘^From .*[0-9]$’. So a paragraph beginning “From now on we ship on Fridays” is left exactly as it was written in a VM folder and comes back ‘>From now on’ in most others.

VM quotes on the way in: mail arriving over POP or IMAP, a message you edit, one you compose or FCC:, a digest you burst, and a folder whose type you convert.

VM does not unescape on the way out, and neither does the common variant. A line that arrived reading ‘>From bob… 2026’ and one VM escaped are the same line afterwards, and no reader can tell them apart. That variant has a name, mboxo, and the loss is the reason it has a rival: mboxrd escapes ‘>From ’ to ‘>>From ’ as well, so that a reader can strip one ‘>’ and get the original back. VM writes neither. It writes mboxcl2 instead, where the boundary is a byte count and nothing is escaped at all, so there is nothing to reverse.

The ‘>’ is permanent, and it outlasts the folder that called for it. A message held in mboxcl2, filed or converted into a From_ folder and brought back to mboxcl2, keeps it: nothing in VM takes off a ‘>’ it put on, so the byte count on the way back describes the quoted line. Saving a message from one folder to another of a different type is enough; vm-change-folder-type is not needed.

One ‘>’ per quoted line is the whole of it, however many trips the message makes. A line already reading ‘>From ’ is left alone, so quoting an already quoted line changes nothing. Only a line matching ‘^From .*[0-9]$’ is ever touched, which is the narrow rule above, so most bodies are not touched at all.

To hold a message exactly as it came, keep it out of From_ folders: file it between mboxcl2 folders, where neither end quotes anything.

VM’s reader is narrower than its writer, on purpose.

Reading a From_ folder, VM takes a line as a separator only if it begins ‘From ’, ends in a digit, and follows an empty line. Writing one, VM quotes without the third test, deliberately: a folder VM writes has to be safe for a reader using the loose rule, which is most of them, and for older versions of VM. So VM quotes some lines it would not itself have mistaken.

The reader’s test is narrower, not exact. A body line that begins ‘From ’, ends in a digit and follows an empty line is read as a separator wherever it was not quoted, in a folder some other program wrote or one assembled by hand, and one message becomes two.

A message must therefore be followed by an empty line, which VM writes. A program that appends to a VM folder without one leaves a message VM reads as part of the message before it.

An mboxcl2 folder is quoted not at all. ¶

Everything above is about From_. mboxcl2 finds the end of a message by counting its bytes, so no body line can be mistaken for a separator and none is altered. That is what Why mboxcl2 above means by storing a message exactly as it came, and it is the whole difference between mboxcl2 and the older mboxcl, which counted the bytes and quoted.

The folder does no quoting; it does not undo quoting done elsewhere. A message that has passed through a From_ folder arrives carrying whatever that folder added, and mboxcl2 stores it faithfully, ‘>’ and all.

A babyl folder VM writes may not be one Rmail can open. ¶

VM quotes a body line that a From_ or an mmdf folder would read as a separator, as above. It does not quote one that a babyl folder would: a body holding the two characters that begin a babyl message, C-_ and C-l at the start of a line, is written as it stands.

VM reads such a folder back correctly, because its own reader takes those two characters for a separator only where a babyl attribute line follows them. Rmail is less forgiving and refuses the file:

Search failed: ",, ?"

having taken the bare separator for the start of a message and then looked for the attribute line that is not there. Other readers of the format differ again: Python’s mailbox.Babyl finds one message more than VM filed.

This is deliberate. Quoting the line would make Rmail read the folder, at the price of a ‘>’ that nothing ever removes, on a message that had none: the same loss described above for From_, in a format where it does not arise today. Babyl is a legacy format here, and the choice was to leave it as it has always been rather than buy Rmail compatibility with a permanent mark on the message.

If you keep mail in babyl folders and want Rmail to be able to open them, convert them with vm-change-folder-type: an mboxcl2 folder stores a message exactly as it came and has none of this.

VM keeps its own state in the messages. ¶

Every message carries an X-VM-v5-Data header holding its attributes, its labels and the summary data VM caches for it, and the first message in the folder carries the folder’s own state as well: the message order, the bookmark, the label list, the summary format, which headers are shown, when the folder was last modified, and for a cache folder what has been retrieved from the server and what deletions the server has not been told about yet.

So the first message is not only a message. Another program that deletes it, or moves it, or rewrites its headers, takes the folder’s order and bookmark with it, and for a cache folder the record of what has been fetched and the deletions still owed to the server. Losing any of them but the last two costs no more than the folder’s order and your place in it, both of which VM writes again; losing the last two means mail fetched a second time, or a deletion the server is never told about, which is why a server cache is a folder to leave to VM.

Read and unread are not where other mailers look. ¶

A message’s attributes live in X-VM-v5-Data and nowhere else by default, so a mailer that reads Status: or X-Status: shows a VM folder as entirely unread. vm-berkeley-mail-compatibility makes VM read and write Status: as BSD Mail does; it is on by default only on the BSDs. Thunderbird is the exception in the other direction: vm-sync-thunderbird-status is t out of the box, so X-Mozilla-Status is kept up to date both ways. See Thunderbird Folders.

Where a VM folder is read differently elsewhere ¶

The escaping rules above have a consequence worth stating plainly: there are folders VM reads correctly that another program does not, and the fault is not in either of them. Two cases, both verified, both one-directional.

A From_ folder VM wrote, read by a program using the plain rule.

VM escapes only a ‘From ’ line that ends in a digit, so a body line such as ‘From the desk of Bob’, standing after a blank line, is left exactly as it was written. VM reads that folder as one message. A program that takes any ‘From ’ line after a blank line as a separator reads it as two, and the second is a fragment with no headers.

An mboxcl2 folder, read by a program that ignores Content-Length:.

Nothing in an mboxcl2 folder is escaped, so every body line beginning ‘From ’ is exposed. A program that honours the header reads the folder correctly. One that ignores it, and some do, splits the folder at those lines.

The other direction is milder. VM does not unescape, so a folder written by a program that doubles its escapes, mboxrd, shows the extra ‘>’ in the text of the message. Nothing is lost and no message is split; it just reads wrong.

There is no setting that makes a folder safe for every reader, because the readers disagree with each other. If a folder has to be handed to a particular program, the thing to know is which rule that program uses.

The short of it: a From_ folder is safe to share with another program if you are content that read and unread will not travel, that the first message is carrying luggage, and that a message whose body has a ‘From ’ line in it may be escaped differently, and so split differently, at each end. A folder VM writes for itself, a cache above all, is better left to VM, and better still written as mboxcl2, where the boundary is a byte count rather than a line that has to be recognised, and where nothing is escaped at all.

The Library of Congress describes the format family and its variants: ‘https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml’.

How VM decides what a folder is ¶

The name decides, and between From_ and mboxcl2 the name is the only thing that can:

1. What the name says, through vm-folder-type-by-extension-alist, matched against the file name’s extension. A folder called sent.mboxcl2 is mboxcl2 wherever it sits. Nothing in a folder can supply this or overrule it. From_ and mboxcl2 look alike: the difference is a Content-Length header that a From_ folder is free to carry as well, so a folder that looks like one is no evidence of either.
2. What VM can work out from the contents, for an existing folder whose name says nothing. BABYL and MMDF are detected from what stands at the front of the file, which is reliable. Telling mboxcl2 from From_ is not: it rests on whether every message carries a length, and VM reads a folder as From_ unless enough of them do. See VM's mbox. A folder read as the wrong one of those two is misparsed rather than refused, which is why the name is worth putting on a folder that has no From_ line to lose.
3. vm-default-folder-type, for a folder that does not exist yet. It decides what VM creates and nothing else, so changing it cannot change how a folder you already have is read. It is From_ on every platform, which is why a folder called INBOX, or one called 2026-08.out, is VM’s mbox and stays it.

Set the default to mboxcl2 and it decides the name as well: a folder VM creates is created as NAME.mboxcl2, whether it is a folder you saved a message to, an FCC: copy or a postponed draft. That is the same rule vm-change-folder-type follows when it converts a folder, and for the same reason: a folder’s type is read back from its name, so mboxcl2 written under a name that says nothing would be read as From_ next time and split wherever a body line begins ‘From ’.

Detection is not the same as knowing. A BABYL file called old.mboxcl2 is read as BABYL, since what is at the front of the file settles it and reading it as mboxcl2 would read nonsense; but a From_ folder that collected a few Content-Length headers, which happens, is a folder VM has to guess about. An empty file gives nothing to detect, and neither does a folder that does not exist yet, which is where the name and the default come in.

The folders VM writes for you ¶

An FCC: copy, a postponed draft and a server cache are all folders VM creates without asking, and each is written in the type the same rule gives: an existing folder keeps the type it has, and a new one is written as its name asks, else as vm-default-folder-type, From_, unless you have said otherwise.

• FCC: and postponed drafts. Name the file for the type and it is written in it, so an FCC: of ~/mail/2026-08.out.mboxcl2 accumulates mboxcl2 and one of ~/mail/2026-08.out accumulates whatever the default is. An existing folder keeps its own type, so an FCC: never converts a folder behind you.
• IMAP and POP caches. Every cache VM creates is named imap-cache-md5.mboxcl2, or pop-cache-..., and written in that type: it holds arbitrary mail that VM alone writes, which is exactly the case the lengths are for. This does not depend on vm-default-folder-type; a cache is named for its type either way.

  A cache made by an earlier VM has no suffix, keeps its name, and is read as From_. Nothing is converted and nothing is refetched. It could be mboxcl2: a cache was written in vm-default-folder-type, which was mboxcl2 on Solaris, AIX and System V until 2026. But VM cannot tell such a cache from a From_ cache that collected a few lengths, and believing a length that is wrong puts a message boundary inside a body, where ignoring one that is right costs a spurious message you can see. So From_, and where the cache looks like the other thing its name is reported once, with the name to rename it to.

Note that a cache file is not the same thing as a local IMAP server holding a copy of a remote mailbox. See IMAP Cache Server.

Converting the caches you already have ¶

Every cache VM creates is mboxcl2 and named for it. A cache from before that has no such name and is read as From_, so it keeps the one weakness mboxcl2 exists to remove: a message whose body holds a line beginning ‘From ’ can split it in two. vm-convert-caches-to-mboxcl2 converts each of those and renames it.

It looks where cache names are built: vm-imap-folder-cache-directory, vm-pop-folder-cache-directory, vm-folder-directory and your home directory. It says how many it found and asks once; with a prefix argument it asks about each. Each conversion is vm-change-folder-type-of-file on that cache, so the previous contents are kept in a backup file and you are asked whether to delete the copy under the old name. Two copies of a large cache on disk is the price of the safety net; delete the backups when you are satisfied.

A cache that cannot be read is left exactly as it was, and the others are converted anyway. A directory that cannot be read is reported the same way and the rest are still searched. Where anything could not be converted the faults are listed in a buffer, *VM cache conversion*, naming each cache or directory and what stopped it; a run that converts everything says so in one line and opens nothing.

A cache you are reading cannot be converted. Quit that folder with vm-quit and run the command again: converting the file under a live folder buffer would leave the buffer holding the cache in the type it no longer is. Nothing is refetched from any server.

Checking a folder ¶

vm-check-folder reports what the folder you are in is and whether it is sound, and writes nothing. It says what type VM reads it as, what its name says it is, what its contents say and what vm-default-folder-type is, how many messages the folder holds against how many the reader finds by walking the separators, and for an mboxcl2 folder whether every message’s Content-Length matches its body. A sound folder is one line in the echo area; anything else gets a report naming each message at fault.

With a prefix argument, vm-check-folder asks for a folder file and checks that, without visiting it. That is how to check the folder most likely to want it: a folder whose name says mboxcl2 and which has a message with no Content-Length cannot be visited at all, so there is no buffer in which to check it. Nothing is written either way.

What the contents say is counted over every message in the folder, and the name is not consulted for it. That is the case a name cannot answer: VM takes a folder’s type from its name, so a folder carrying a Content-Length that fits on every message, under a name that does not say mboxcl2, is read as From_ and split wherever a body line begins ‘From ’. Visiting such a folder warns, and the check is what settles it: the warning looks at the first two messages, which is as much as a folder being visited can afford to read. The report then names the rename and the conversion.

A cache whose name states no type is reported too, and vm-convert-caches-to-mboxcl2 named as what converts it. Nothing in such a cache is wrong: read as From_ it is From_, and the messages in it now are delimited correctly. What it lacks is the guarantee mboxcl2 gives, so the report says so and names the command rather than calling it a fault. It is the one place a reader is told, since the warning at visit time fires only for a cache that carries lengths.

A wrong length is what the command exists for, because it is the only one of these faults that gives no other sign. A missing length is refused when the folder is visited, and a folder VM cannot parse fails loudly, but a length that is merely wrong opens without complaint: the reader falls back on searching for the next separator when the count does not land on one, so VM reads the folder correctly while anything that believes the header, which is what the format is for, takes the wrong bytes.

A length short by the newlines at the end of a body is not a fault. The reader skips any number of them past the count, because some mailers do not count the last one, so a folder they wrote is sound as far as VM is concerned.

Converting a folder ¶

vm-change-folder-type converts the folder you are in. With a prefix argument it asks for a file and converts that instead, without visiting it, which is the only way in when a folder cannot be read. With two prefix arguments it asks for a file and then for where to write the conversion: the result goes to the file you name and the folder you converted is left exactly as it was, with no backup made and nothing offered for deletion, since nothing of it was touched. That is the way to look at a conversion before trusting it, and the way to repair a copy of a folder rather than the folder. It is a good idea to keep all your mail folders in a single format in order to avoid incompatibilities.

A name that cannot hold the type is refused rather than written, and the command says what to call it instead. An mboxcl2 folder called out.mbox would be read back as From_ and split wherever a body line begins “From ”, and one called out with no extension the same, so neither is written. Nothing is asked of a name that could not state the type anyway: From_ is the type a folder has when its name says nothing, and a reader who has emptied vm-folder-type-by-extension-alist has said that names mean nothing here.

Converting to and from plain mbox ¶

Plain mbox is VM’s From_ type: no Content-Length headers, the end of a message found by the next line beginning “From ”. It is what other Unix mail programs mean by mbox, and what to convert to before handing a folder to one of them.

To convert the folder you are reading:

1. M-x vm-change-folder-type RET From_ RET
2. Answer the question about the file left behind. Converting sent.mboxcl2 writes sent, and sent.mboxcl2 is then offered for deletion; the folder as it was is kept in a backup file whichever you answer.
3. M-x vm-check-folder to see that the result is what you meant.

To convert a folder you are not reading, or one VM will not open, give the command a prefix argument and it asks for the file: C-u M-x vm-change-folder-type RET From_ RET.

Going the other way is the same command with mboxcl2, and it is worth knowing what it costs: every body is measured and a header added, so the folder is rewritten entirely, and a mailer that does not understand Content-Length will still read it, since an mboxcl2 folder is a From_ folder with an extra header. What such a mailer will not do is keep the header right when it writes, which is how a folder ends up with lengths that lie. vm-check-folder is how you find out.

Note: Converting to From_ does not put back what mboxo quoting took out. A body line that began “From ” was rewritten to “>From ” when it was first written into an mbox folder, and nothing can tell that apart from a line the author wrote as “>From ”. Converting away from mboxcl2 and back does not lose anything further, but neither does it recover what an earlier mbox writer already changed.

The name moves with the type, since the name is what states the type: a folder converted to mboxcl2 is written as name.mboxcl2, one converted away from it loses the extension, and the file left behind under the old name is offered for deletion once the new one is on disk.

From_ is the exception, and is never put into a name that has not got it: it is the type a folder has when its name says nothing about it, so a folder called INBOX converted to From_ is still INBOX rather than INBOX.mbox. A folder you called sent.mbox keeps that name, since the name already says what the folder now is. Keeping it is allowed, and it is worth knowing what you are keeping: two folders holding the same mail, of which the old one is the copy VM is no longer looking at. The folder as it was is kept in a backup file either way, named as Emacs names one when saving a buffer.

A conversion that would overwrite an existing folder is refused rather than asked about. Where the name already states the new type, converting mboxcl2 to mboxcl2 to recompute every length, which is the repair described above – nothing is renamed and nothing is offered.

The system default format on most flavors of Unix (except Solaris, AIX and System V) is referred to as From_. It is the traditional Unix mbox format. In this format, a leading separator line and a trailing separator line are added to each message. The leading separator line starts with the string “From ”. The trailing separator line is a blank line. VM actually adds two blank lines at the end for clarity.

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

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

VM will not create a BellFrom_ folder. It is not among the types vm-default-folder-type offers, nor among those vm-change-folder-type offers to convert to, because a folder VM writes as one cannot be read back as one: having no trailing blank line, the format has no signature of its own, so VM reads it as From_ and each message swallows the headers of the next. Reading is unaffected, which is what vm-default-From_-folder-type above is for. Setting vm-default-folder-type to BellFrom_ by hand still works, and still has that result, so VM says so as it starts.

Solaris, System V and AIX operating systems use another variant of the mbox format, in which each message carries a Content-Length header giving the length of its body, and that count rather than the next “From ” line says where the message ends. VM refers to this format as mboxcl2.

Asking for it used to mean setting vm-trust-content-length, which told VM to believe a Content-Length header wherever it found one. That option is deprecated: it made a statement about every folder read, in order to say something about one, and nothing stops a message carrying such a header that means something else. Name the folder for the type instead, or set vm-default-folder-type; both are described below.

The four mbox variants ¶

Mail folders written as mbox come in four variants, named by convention rather than by any standard. They differ in two things: what marks the end of a message, and whether the message is modified to make that work. There is no file name extension, magic number or header that tells them apart, so the names below are a way of talking about folders rather than something a program can detect.

mboxo

The end of a message is the next line beginning “From ”. A body line that begins that way is therefore changed on writing: “From ” becomes “>From ”. The change is not reversible, because a line that already read “>From ” is left alone, and a reader cannot tell the two apart. VM’s From_ and BellFrom_ are this variant.

mboxrd

As mboxo, but “>From ” becomes “>>From ” as well, so the change can be undone exactly. VM does not write this variant.

mboxcl

The end of a message is found from its Content-Length header, and body lines are still quoted as in mboxo. VM does not write this variant: quoting a body it has already measured alters the message for no gain.

mboxcl2

As mboxcl, but with no quoting at all: the count alone says where the message ends, so the body is stored exactly as it arrived. This is VM’s mboxcl2 folder type.

VM reads and writes the first and the last of these. It has no name of its own for mboxrd, and does not write mboxcl.

VM wrote mboxcl until 2026: these folders were given a Content-Length header and had their bodies quoted. Reading is unaffected either way, since VM has never unquoted a body, so a folder written before that change reads exactly as it did; what changed is that new messages are no longer altered on the way in.

The folder type was called From_-with-Content-Length until then, after the mechanism rather than the format. The old type name still works wherever a type is given: in vm-default-folder-type, by vm-change-folder-type, and in an index file written before the change. It is not going to be removed. The option was renamed with it, and setting it under its old name reports the current one.

The reason to care is that the first three change the message. A folder kept for its own sake (an archive, or anything you may want to verify later) is better in a format that does not, and mboxcl2 is the only one of the four that does not. It is what vm-default-folder-type should be set to for a folder kept as a record. All four are described in the Library of Congress’s registry of formats for digital preservation, which exists to record how well a format suits keeping things: mboxcl2 is fdd000387, mboxcl fdd000386, mboxrd fdd000385 and mboxo fdd000384. Those are descriptions rather than standards: they say what each format is, not what anyone is obliged to write.

The reason not to care is interoperability, and it cuts the other way. A program that does not honour Content-Length, which is most of them – will read an mboxcl2 folder as mboxo, and split it wrongly at the first body line beginning “From ”, silently. Content-Length formats are right for folders you keep and wrong for folders you hand to other tools.

Which of the two VM reads a folder as is not something it can tell from the file, since nothing in an mbox says which variant it is. There is no extension, media type or magic number for any of them, and the Library of Congress descriptions say as much. VM looks at the first message: if it has a Content-Length header and vm-trust-content-length is set, the folder is read by its counts, and otherwise by its ‘From ’ lines. A folder read the wrong way is not damaged, but it is a different folder: a body line beginning ‘From ’ starts a new message under one reading and does not under the other.

On the formats themselves, see the Library of Congress descriptions at https://www.loc.gov/preservation/digital/formats/fdd/fdd000387.shtml for mboxcl2 and fdd000383 for the mbox family it belongs to. The four names were settled on by Daniel J. Bernstein, Rahul Dhesi and others in 1996; they are a convention for talking about folders rather than anything a program can detect.

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

That is what makes mail from another reader easy to bring over. An Rmail folder can be visited as it stands, or converted first with Emacs’s M-x unrmail. An MH folder becomes a folder VM can read by running MH’s own packf or packmbox over it, which writes the messages out in one of the formats above. Once such a folder is open, vm-change-folder-type writes it out in whichever format you have settled on.

Maildrop specification ¶

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

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

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

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

For SSL, Emacs makes the connection itself where it was built with GnuTLS, and VM runs the stunnel program where it was not. That is what vm-stunnel-program says: its default is nil, meaning Emacs’s own, on an Emacs with GnuTLS, and ‘"stunnel"’ on one without, which works if that program is in your command search path. An Emacs without GnuTLS on a machine without stunnel cannot reach a server that requires SSL at all. Depending on the version of ‘stunnel’ program you are using, you may need to define a configuration file for ‘stunnel’. If you need it, you should set the variable vm-stunnel-program-additional-configuration-file to the location of the configuration file. (Consult the doc string of the variable and the manual of the ‘stunnel’ program to find out what to put in the configuration file.)

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

HOST is the host name of the mail server.

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

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

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

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

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

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

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

machine HOST login USER password PASSWORD port PORT

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

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

Troubleshooting mail servers ¶

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

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

How many of them are kept is one variable per protocol:

User Option: vm-pop-keep-trace-buffer ¶

The number of POP session trace buffers that should be

  retained for debugging purposes.  If it is nil, then no trace
  buffers are kept.

Default value: 1

User Option: vm-imap-keep-trace-buffer ¶

The number of IMAP session trace buffers that should be

  retained for debugging purposes.  If it is nil, then no trace
  buffers are kept.

Default value: 1

POP Folders ¶

Command: vm-visit-pop-folder folder &optional read-only &rest rest ¶

Visit a POP mailbox. VM will present its messages to you in the usual way. Messages found in the POP mailbox will be downloaded and stored in a local cache. If you expunge messages from the cache, the corresponding messages will be expunged from the POP mailbox.

First arg FOLDER specifies the name of the POP mailbox to visit. You can only visit mailboxes that are specified in vm-pop-folder-alist. When this command is called interactively the mailbox name is read from the minibuffer.

Prefix arg or optional second arg READ-ONLY non-nil indicates that the folder should be considered read only. No attribute changes, messages additions or deletions will be allowed in the visited folder.

The cache lives in the directory named by vm-pop-folder-cache-directory, or in vm-folder-directory if that one is not set. Deletions reach the POP server when you save the changes with vm-save-folder, not when you make them.

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

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

 ((POPDROP NAME) ...)

POPDROP is a POP maildrop specification (maildrop specification).

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

For example:

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

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

IMAP Folders ¶

Command: vm-visit-imap-folder folder &optional read-only &rest rest ¶

Visit a IMAP mailbox. VM will present its messages to you in the usual way. Messages found in the IMAP mailbox will be downloaded and stored in a local cache. If you expunge messages from the cache, the corresponding messages will be expunged from the IMAP mailbox when the folder is saved.

When this command is called interactively, the FOLDER name will be read from the minibuffer in the format "account-name:folder-name", where account-name is the short name of an IMAP account listed in vm-imap-account-alist and folder-name is a folder in this account.

Prefix arg or optional second arg READ-ONLY non-nil indicates that the folder should be considered read only. No attribute changes, messages additions or deletions will be allowed in the visited folder.

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

A cache folder is named after the MD5 of the maildrop it holds, so it can be neither read nor typed by hand. M-x vm-folder-cache-file in the folder says which file it is; it works for POP folders too, and answers nothing for a folder that is a file in the first place. Only the scheme, the host, the mailbox and the login name go into the name, so imap and imap-ssl for one mailbox share a cache and changing your password does not orphan it.

The port is left out along with them, and that is a restriction: two IMAP servers on one host, reached on different ports with the same login name and the same mailbox, name the same cache file and so share one. Visiting the second gets you the first one’s folder. Give them different host names, through /etc/hosts or an SSH tunnel on a name of its own, and the caches are separate again.

The port cannot simply be added: every cache file that exists is named without it, so putting it in would rename all of them and lose what they hold. A host running two mail servers on different ports for one account is rare enough that the caches you already have are worth more.

While VM is talking to the server ¶

VM’s IMAP and POP operations are asynchronous: they do not block Emacs. Fetching mail, loading a message body, sending your flag changes, expunging, saving, quitting, synchronising, filing a copy of a message you send: all of them go on in the background, and Emacs answers you throughout. What you see of it is in the mode line of the folder, its summary and its presentation buffer, which say what the folder is doing:

VM: inbox   3 (of 412)   fetching 24/340 +1 

‘fetching’ is what it is doing; ‘24/340’ is how far it has got, which moves as each bunch of messages arrives; ‘+1’ is one more piece of work waiting for it. The count appears once VM knows how many messages it is fetching, and a piece of work with nothing to count (sending your flag changes, say) shows none. It is shown in the face vm-net-session-face, which inherits mode-line-emphasis; give that face a background if you want it louder. When the mode line says nothing there, VM is not talking to that folder’s server.

A folder is not locked while this goes on. You can read it, move about it, delete, undelete, mark, label and expunge as usual. What VM does with the work you ask for depends on whether it needs the server:

• Anything local happens at once, as it always did.
• Anything that needs the server and can wait (a body to be shown, the flags you have changed, an expunge, a save) is done when the session running now has finished. A folder runs one session at a time: two writing into it would interleave two sets of messages, flags and expunges in one buffer and one cache file.
• Anything that must have an answer before it can go on (saving or copying a message whose body is still on the server, and completing a folder name) waits for it. Those are the two places VM still waits on purpose, and C-g works throughout.

New mail arrives into the folder as it is fetched, a bunch at a time, rather than all at the end, so a large mailbox fills in while you read it.

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

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

 ((IMAPDROP NAME) ...)

IMAPDROP is an IMAP maildrop specification (maildrop specification).

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

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

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

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

The variable vm-imap-server-list, used in older versions of VM, was deprecated in 8.1.0 and is gone; vm-imap-account-alist replaces it, in a different format that names each account.

IMAP Synchronization ¶

The cache folder and the folder on the IMAP server are partially synchronized every time vm-get-new-mail is invoked. This involves (i) writing the changed attributes and labels to the server, (ii) updating the attributes and labels in the cache folder based on the server data, (iii) expunging messages in the cache folder that have been expunged on the server, and finally, (iv) retrieving any new messages on the server.

VM remembers the UID of every message it has retrieved, in the cache folder’s own X-VM-IMAP-Retrieved header, and step (iv) passes over a message that record already names. That is what makes deleting a message here stick, rather than the message arriving again with the next g. A cache that has lost messages the record still names (one restored from a partial backup, say) is short of them for the same reason; C-u C-u g is what asks for those.

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

The synchronization can also be asked for on its own:

Command: vm-imap-synchronize &optional full ¶

Synchronize the current folder with the IMAP mailbox. Changes made to the buffer are uploaded to the server first before downloading the server data. Deleted messages are not expunged.

Prefix argument FULL says to write every message’s attributes to the server, rather than only those of the messages whose attributes changed in this session, and to fetch a message the cache no longer holds rather than leaving it alone. This is useful for saving offline work on the cache folder, whose expunges are sent whether FULL is given or not: VM records them as the reader makes them.

FULL used to delete on the server every message the mailbox had and the cache did not. A damaged cache says the same thing as a reader who expunged, so that destroyed mail nobody asked it to (emacs-vm/vm#752).

Gmail, and why labels do not stick ¶

Gmail’s IMAP is a mapping onto Gmail’s own model rather than an implementation of the protocol, and the differences are not ones VM can paper over.

A label is a mailbox.

A message carrying two labels appears in two mailboxes, and All Mail holds every message once. Applying a label is a UID COPY into the mailbox of that name, not a flag.

IMAP keywords are not labels.

A VM label is an IMAP keyword on the wire. Gmail accepts a STORE of an arbitrary keyword, answers success, and does not keep it, with no error at any point. VM notices and says so once per session, and keeps the label in the folder. It used to be erased in the same breath: the flags read back from the server replaced the folder’s labels with what the server had, which was nothing, so setting a label against Gmail looked like a command that did nothing. A label now stays where you set it and goes no further, no other client sees it, and it is lost with the folder’s cache file. Nothing VM can do at the protocol level puts it on the server.

\Deleted does not delete.

Setting the flag marks nothing for removal in the usual sense. What deletes is an EXPUNGE from All Mail, or moving the message to [Gmail]/Trash.

Gmail advertises its own extension, X-GM-EXT-1 in the CAPABILITY response, whose X-GM-LABELS does the mapping properly, and that is what clients written for Gmail use. VM does not use it today.

What you can do about it ¶

The workable arrangement is to put a local IMAP server in front of Gmail and let VM talk to that. Keywords persist against a local server, so labels behave, and the local server is faster besides. See IMAP Cache Server.

Be clear about the ceiling: labels then live on your machine. A keyword set in VM reaches the local server and stops there, because Gmail has nowhere to put it and the sync tools do not translate keywords into labels. The reverse direction is possible with a tool that carries Gmail’s labels, offlineimap writes them as an X-Keywords: header with synclabels = yes, but that is a header rather than a keyword, so VM does not read it as labels either. If your labels matter across machines and clients, they cannot be VM labels against Gmail today.

A local IMAP server as a cache ¶

A remote server that is slow to answer makes every operation slow, because each one is a round trip. Gmail is the usual example. The arrangement that fixes it is not a VM feature at all: run an IMAP server on your own machine, hold a copy of the remote mailbox in it, and point VM at localhost. VM then sees a fast IMAP server, and something else deals with the slow one on its own schedule.

Two things follow, and the second is the one people do not expect:

• Every VM operation answers at local speed rather than at the remote’s.
• Changes are queued for you. A local server accepts a flag change immediately and its sync tool pushes it when the remote is reachable, so VM neither waits nor fails when the network is down.

The structure of it ¶

Three pieces:

1. An IMAP server on the local machine. dovecot is the usual choice.
2. A sync tool that mirrors the remote mailbox into it. mbsync (from isync) is the usual choice; offlineimap and imapsync are alternatives.
3. Optionally something that runs the sync when mail arrives rather than on a timer. goimapnotify watches the remote with IMAP IDLE and runs the sync tool.

VM’s part is one line: a maildrop specification naming localhost and the password you gave the local server.

(setq vm-imap-account-alist
      '(("imap:localhost:143:INBOX:login:you@example.com:*" "local")))

Setting it up ¶

What follows is the structure rather than a recipe, because the paths and the service manager differ by system. Use your packaging’s own locations: a MacPorts install puts configuration under /opt/local/etc and its store under /opt/local/var, Homebrew uses /opt/homebrew or /usr/local, and a Linux distribution package uses /etc/dovecot and /var/mail. dovecot -n prints the configuration actually in force, which is the quickest way to find out where yours lives.

1. A user and a directory for the store. Create a system user that owns the mail store, make its directory, and give it to that user with permissions 0700. On Linux the package usually does this; on macOS you create the user yourself, with a free numeric id, and it will not appear in the graphical user list.
2. Virtual users, one per account. A local server needs an account for VM to log in to, and it need not correspond to a Unix user. Generate a hashed password with

   doveadm pw -s BLF-CRYPT
   

   and put the hash in dovecot’s user database, readable by the authentication user and nothing else. Use the same account names as the remote ones if you want to keep your own bearings.

3. Passwords where the sync tool can reach them, rather than in its configuration file. mbsync takes PassCmd, which runs a command and reads the password from its output, so any secret store will do: the Keychain on macOS through security find-generic-password, or secret-tool, pass or gpg on other systems. Two passwords are involved per account and they are easy to confuse: the remote server’s, which the sync tool needs, and the local server’s, which both the sync tool and VM need.
4. A sync channel per account, with its own state directory, so that one account’s state cannot be confused with another’s.
5. Run it. A timer is the simple answer, through launchd on macOS or a systemd user timer on Linux; goimapnotify on the remote account is the responsive one, running the sync when the server says something has arrived. A service started by the system does not inherit your interactive PATH, so name programs by absolute path in whatever you install there.

What to watch ¶

• A resync from scratch changes UIDVALIDITY. Deleting the local store and syncing again gives every message a new UID, and VM notices: it treats the mailbox as a different one, which is the correct response and not a fault. Expect it after any rebuild of the local store.
• A cache file is not the cache server. VM keeps its own local copy of a server folder, named imap-cache-md5.mboxcl2 (see Folder types), and that is a separate thing from the local IMAP server’s own store. Running a cache server does not remove VM’s cache file, and the two hold the same mail for different reasons.
• Metadata is where the arrangement leaks. mbsync maps folders and flags, and a keyword set in VM stops at the local server (see Gmail). Verify what reaches the remote before relying on it.
• Test the pieces separately. doveadm mailbox list and doveadm fetch against the local server answer “is the mail here”, which is a different question from whether VM can see it. Where a notification tool is involved, note that it can exit successfully having displayed nothing, so its exit status is not evidence.

Differences in folder summary ¶

Most current versions of Thunderbird hide deleted messages from the summary window. However, the deleted messages are still present in the folder. They are expunged from the folder only when you do some bulk operation such as “purge” or “compact”. Since the deleted messages are still present in the folder, when you visit the folder in VM, the deleted messages will appear in the VM summary buffer. This is normal.

If you want VM’s summary buffer to appear similar to Thunderbird’s, you can use the vm-summary-faces-hide command. See Hiding summary lines.

How the inter-operation works ¶

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

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

The default gives the behaviour described above:

User Option: vm-sync-thunderbird-status ¶

If set to t, VM synchronizes its headers with the headers of Thunderbird so that full interoperation with Thunderbird becomes possible. If it is set to read-only then VM reads the Thunderbird status flags, but refrains from updating them. If it is set to nil then VM makes no attempt to read or write the Thunderbird status flags.

Default value: t

Under read-only the changes you make are lost when you quit VM, since they were never written back. Under nil they survive inside VM and mean nothing to Thunderbird.

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

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

Recovering Folders ¶

When you visit a folder, VM looks for an auto-save file modified more recently than the folder file. One that exists is a good sign that Emacs or your operating system crashed while VM was visiting the folder, so VM says so in the echo area and visits the folder in read-only mode. Read-only mode is what protects the auto-save file: nothing can modify the folder, so Emacs has no new changes to write over it. While the folder is read-only:

• VM retrieves no new mail for it.
• No summary is generated.
• MIME is not decoded.

The last two are to catch your attention.

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

In response to vm-recover-folder, Emacs displays a detailed directory listing showing the folder file and the auto-save file, and asks whether you want to recover from the auto-save file. Their sizes are the rule of thumb:

Yes, the auto-save file being larger

The folder buffer takes the contents of the auto-save file and VM re-parses it. Buffer and disk copy now differ, so VM fetches no new mail for the folder until they agree: when you are satisfied that the recovered folder is whole and intact, type S to save it, after which g retrieves new mail as usual.

No, it being significantly smaller

Either Emacs did not finish writing it during the crash, or it holds an expunge you had not yet committed to disk, and answering “no” may mean doing that expunge again. That is better than not knowing whether the file was truncated. Type C-x C-q, which is vm-toggle-read-only in a folder buffer, to take the folder out of read-only mode; read and retrieve mail normally, the auto-save file staying on disk and ignored.

Recovering a POP or IMAP folder modified during a previous crash works the same way, but its auto-save file holds less that is of any use. Synchronizing an IMAP folder saves only the changes made during the current VM session, and the changes in the auto-save file were made in an earlier one, so they cannot reach the server at all. Answering “no” and taking the folder out of read-only mode with C-x C-q is the better course for a server folder.

Recovering Message Compositions ¶

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

Recovering Sessions ¶

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

If you do answer “yes”, Emacs loads the auto-save file into a buffer. The auto-save file is still on the disk and is deleted when you save the buffer, so examine the folder before you save it:

1. Run M-x vm-mode in the buffer holding the folder.
2. Save it once you are satisfied that it is not damaged. Or kill the buffer, where the auto-saved version is not one you trust: VM asks whether you mean to kill it and then whether to delete the auto-save file, and answering “yes” to the second is what loses the auto-saved folder for ever.

Backing Up a Folder ¶

Emacs backs a file up on the first save of its buffer and not again, so a folder saved earlier in the session has no copy of what is on disk now. To make one:

Command: vm-backup-folder ¶

Keep a copy of this folder as it is on disk. Emacs backs a file up on the first save of its buffer and not again, so a folder saved earlier in this session has no copy of what is on disk now. This makes one whatever make-backup-files says.

The copy is named as Emacs would name a backup: backup-directory-alist decides where it goes and the numbered-backup settings how many are kept, so it lands where your other backups are.

It copies the file and not the buffer, so changes you have not saved are not in it. Save the folder first to keep those.

Run it from anywhere in a folder, the summary included. backup-buffer does nothing in a summary or presentation buffer, those visiting no file, which is what makes a command of VM’s own worth having.

C-u C-u S does it as part of a save, vm-save-folder handing its prefix argument to save-buffer, which documents that one. It saves as well, and does nothing at all where the folder is unmodified.

To keep a copy at every save instead of the first, clear the flag Emacs sets when it has backed a buffer up:

(add-hook 'vm-mode-hook
          (lambda ()
            (add-hook 'before-save-hook
                      (lambda () (setq buffer-backed-up nil))
                      nil t)))

A drafts folder you are not visiting is a file VM appends to rather than a buffer it saves, so nothing backs it up. Visit it to have the copies, or keep them another way.

Reverting a Folder ¶

If you have made changes to a mail folder which you would like to cancel and go back to the version currently on the disk, use the Revert Folder entry in the Folder menu, or:

Command: vm-revert-folder ¶

Revert the current folder to its version on the disk. The summary and presentation buffers are killed, the file is read again, and the folder is visited afresh with the access method it had, so an IMAP or POP folder comes back connected rather than as a plain file.

Also available as vm-revert-folder.

Emacs’s own revert-buffer is not recommended: it reads the file back without VM’s bookkeeping, so the folder buffer and VM’s idea of it part company.

Included text ¶

As mentioned above, the commands vm-reply-include-text and vm-followup-include-text provide “included text” from the original message in your reply. In addition, you can use C-c C-y (vm-yank-message) inside a mail buffer to include text from any desired mail message. This is a more general mechanism for citing message text in the composed message. (The composed message does not have to be a reply. Neither do the cited messages have to be the messages you are replying to.)

Citing message text is a tricky business because the original message could be a MIME message with encoded text or formatted text along with embedded images and attachments. By default, VM uses its MIME displaying mechanism to extract the included text to be cited in replies. The quoted text is then similar to what appears in the message Presentation buffer. However, the MIME attachments are not included by default. They are shown in the message composition buffer with attachment buttons labelled similar to:

[DELETED ATTACHMENT mary.jpg, image/jpeg]

If you set the variable vm-include-mime-attachments then the attachment buttons are converted to actual attachments before the message is sent. The format of the button in this case looks like:

[ATTACHMENT mary.jpg, image/jpeg]

When citing a multipart/alternative MIME component, VM uses the variable vm-mime-alternative-yank-method to decide which alternative should be cited. It can be defined in a similar way to the variable vm-mime-alternative-show-method. (see MIME multipart/alternative.)

Filling included text ¶

If the included text contains long lines, i.e., lines longer than the normal window width, you might want to fill paragraphs. It is not necessary to do so. If you send a message with long lines in it, VM will MIME-encode the text so that it can be transported reliably and your recipients can use their own email readers to format the long lines. Keep in mind also that only running text should be filled. Tables, figures and program code have line breaks that are significant, and they may be destroyed by filling.

You can invoke automatic filling of paragraphs by setting the variable vm-fill-paragraphs-containing-long-lines-in-reply. Like its namesake used in message presentation (see Paging), it should be set to a positive numerical value N or the symbol window-width. Setting it to nil disables paragraph filling. If filling is used, the fill column is controlled by the variable vm-fill-long-lines-in-reply-column.

You can also invoke the command vm-fill-long-lines-in-reply interactively. It uses the two variables mentioned above to decide when and how to fill text. If the vm-fill-paragraphs-containing-long-lines-in-reply is nil, it assumes that it should fill any lines longer than the current window width.

Finally, you can fill individual paragraphs manually using C-c C-q (mail-fill-yanked-message).

Alternative methods to include text ¶

The method of MIME decoding for included text is relatively new in VM. The older methods are the inclusion of plain text, due to Kyle Jones, and the inclusion of text from the Presentation buffer, due to Robert Fenk.

The Kyle Jones method of plain text inclusion is enabled by setting the variable vm-include-text-basic to t. Setting the variable to nil returns you to the default behaviour. You can set the variable vm-included-mime-types-list to additional MIME type/subtype pairs that should be included in cited text. But it may not produce good results because the handling of MIME types is not available in the basic text inclusion method.

The Robert Fenk method of text inclusion from the Presentation buffer is enabled by setting the variable vm-include-text-from-presentation to t. In this case, the text display from the Presentation buffer is copied verbatim as the quoted text.

Options ¶

The attribution is a line of text saying who wrote what is being included, inserted before it. See Summaries, for the format.

User Option: vm-included-text-attribution-format ¶

String which specifies the format of the attribution that precedes the included text from a message in a reply. See the documentation for the variable vm-summary-format for information on what this string may contain. Nil means don’t attribute included text in replies.

Default value: "%F writes:\n"

VM normally includes only the body text from the cited messages. If you wish, you can include also the message headers by customizing the variables vm-included-text-headers and vm-included-text-discard-header-regexp.

Forwarding ¶

Typing z (vm-forward-message) puts you into a VM Mail mode buffer just like m, except that the current message appears as the body of the message in the VM Mail mode buffer.

The forwarded message is encapsulated as specified by the variable vm-forwarding-digest-type. Recognized values are nil, "mime", "rfc934" and "rfc1153". The default is "mime".

If vm-forwarding-digest-type is set to nil, the forwarded message is not encapsulated. It is included in a plain text form. Any attachments of the original message appear as attachment buttons in the composition. They will be replaced by actual attachments when the message is sent.

The key Z (vm-forward-message-plain) allows you to use plain-text forwarding directly, without needing to alter vm-forwarding-digest-type.

If you have previously saved any attachments in the messages being forwarded, those attachments are normally fetched and included in the forwarded messages. You can inhibit this by setting the variable vm-mime-forward-saved-attachments to nil. Messages are then forwarded with external references to saved attachments. If the recipients have access to the file system where attachments are saved, they will still be able to view them. (This may be appropriate if the attachments are saved in some shared file space, or if you wish to suppress the attachments in the forwarded messages.)

You can control which header lines are included in forwarded messages via the variables vm-forwarded-headers and vm-unforwarded-header-regexp (and their counterparts vm-forwarded-headers-plain and vm-unforwarded-header-regexp-plain for plain-text forwarding). How they are used differs based on the form of forwarding used.

• For encapsulated forwarding, the default is to forward all the headers, but you can limit the forwarded headers by setting vm-unforwarded-header-regexp to a regular expression. All the headers matching the regular expression will be omitted. If this variable is set to nil, then its value is ignored and only the headers listed in vm-forwarded-headers are forwarded.
• For plain-text forwarding, done by the Z command, the variables vm-forwarded-headers-plain and vm-unforwarded-header-regexp-plain are used in a similar way. If the latter is set to a regular expression, then the headers matching it are omitted. Otherwise, only the headers listed in vm-forwarded-headers-plain are included. The default settings forward only the headers “From”, “To”, “Cc”, “Subject”, “Date” and “In-Reply-To”.

Command: vm-forward-message-all-headers ¶

Like vm-forward-message but forwards all the headers.

User Option: vm-forwarding-subject-format ¶

String which specifies the format of the contents of the Subject header that is generated for a forwarded message. See the documentation for the variable vm-summary-format for information on what this string may contain. The format should *not* end with nor contain a newline. Nil means leave the Subject header empty when forwarding.

Default value: "forwarded message from %F"

The forwarded message is flagged ‘forwarded’ when the message is sent.

Digests ¶

The command @ (vm-send-digest) works like z except that a digest of all the messages in the current folder is made and inserted into the VM Mail mode buffer. Also, vm-send-digest can be applied to just marked messages. See Selecting Messages. The message encapsulation method is specified by the variable vm-digest-send-type, which accepts the same values as vm-forwarding-digest-type. All the messages included in the digest will be flagged “forwarded” when the digest message is sent.

If you give vm-send-digest a prefix argument, VM will insert a list of preamble lines at the beginning of the digest, one line per digestified message. The variable vm-digest-preamble-format determines the format of the preamble lines. If the value of vm-digest-center-preamble is non-nil, the preamble lines will be centered.

Resending ¶

B (vm-resend-message) resends a message: it goes on with its original headers, so that you do not appear to have intervened. VM adds a ‘Resent-To’ header for you to fill in with the new recipients, C-c C-c sends it as usual, and the message is flagged “redistributed”.

Caution: A resent message reaches its new recipients looking as though it came from the original sender, and a reply to it goes to that sender. Only a reader who thinks to look at the Resent-To header sees otherwise.

Manual control of thread indentation ¶

When you deal with long discussions in mailing lists or newsgroups, you would find that threads get very deep and their indentation in the Summary window is not entirely helpful. You can temporarily promote the subthreads to higher level so that you can view the threading relationships more clearly.

Command: vm-promote-subthread n ¶

Decrease the thread indentation of the current message and its subthread by N steps, N being the prefix argument.

A prefix argument of 0 decreases the indentation all the way to 0, so the message reads as the root of a thread.

Its < binding is one of the optional ones, installed by (vm-current-key-bindings) and described under Paging; without that, run it with M-x.

Command: vm-demote-subthread n ¶

Increase the thread indentation of the current message and its subthread by N steps, N being the prefix argument.

A prefix argument of 0 puts the indentation back to the one the message’s thread level gives it, with no offset.

That one is > with the same optional bindings installed.

Both of these commands alter the thread indentation for the current session only. The next time you visit the folder, the threads will be displayed using the standard indentation.

Generic selectors ¶

any

matches any message.

header

matches message if ARG matches any part of the header portion of the message; ARG should be a regular expression.

text

matches message if ARG matches any part of the text portion of the message; ARG should be a regular expression.

header-or-text

matches message if ARG matches any part of the headers or the text portion of the message; ARG should be a regular expression.

header-field

matches messages if the header field named ARG1 has text matching ARG2.

Selectors based on message headers ¶

author

matches message if ARG matches the author; ARG should be a regular expression.

author-or-recipient

matches message if ARG matches the author of the message or any of its recipients; ARG should be a regular expression.

recipient

matches message if ARG matches any part of the recipient list of the message. ARG should be a regular expression.

principal

matches message if ARG matches any part of the ‘Reply-To’ header of the message. ARG should be a regular expression.

addressee

matches message if ARG matches any part of the ‘To’ header of the message, either an address or a full name. ARG should be a regular expression. Unlike recipient, this does not consider the ‘Cc’ or ‘Bcc’ headers.

uninteresting-senders

matches message if its author matches vm-summary-uninteresting-senders, which is normally set to match yourself. This is the selector behind outgoing, and takes no ARG.

outgoing

matches message if your are the author of it, i.e. if the author matches vm-summary-uninteresting-senders.

in-bbdb

matches message if its addresses are in the BBDB. With an optional first argument you can specify the address class (authors or recipients) . With an optional second argument t, the selector checks only the first address specified in the message. Examples:

(in-bbdb authors)

(in-bbdb recipients t)

subject

matches message if ARG matches any part of the message’s subject; ARG should be a regular expression.

sortable-subject

matches message if ARG matches the subject as sorting reads it, with the prefixes, suffixes and insignificant characters left out that vm-subject-ignored-prefix, vm-subject-ignored-suffix, vm-subject-tag-prefix, vm-subject-tag-prefix-exceptions and vm-subject-significant-chars describe. So a reply and the message it answers match alike, whatever ‘Re:’ the reply carries.

sent-after

matches message if it was sent after the date ARG. A fully specified date looks like this:

``31 Dec 1999 23:59:59 GMT''

although the parts can appear in any order. You can leave out any part and it will default to the current date’s value for that part, with the exception of the ‘hh:mm:ss’ part which defaults to midnight.

sent-before

matches message if it was sent before the date ARG. A fully specified date looks like this:

``31 Dec 1999 23:59:59 GMT''

although the parts can appear in any order. You can leave out any part and it will default to the current date’s value for that part, with the exception of the hh:mm:ss part which defaults to midnight.

older-than

matches message if it is more than ARG days old (today = 0)

newer-than

matches message if it is at most ARG days old (today = 0)

message-id

matches message if its Message ID has a string matching ARG

uid

matches message if its IMAP UID is ARG (for IMAP folders)

uidl

matches message if its POP UIDL is ARG (for POP folders)

spam-score

matches message if its spam score is at least ARG. See vm-spam-score-headers for configuration.

Selectors based on message attributes ¶

deleted

matches message if it is flagged for deletion.

undeleted

matches message if it has not been deleted.

edited

matches message if it has been edited.

unedited

matches message if it has not been edited.

filed

matches message if it has been saved with its headers.

unfiled

matches message if it has not been saved with its headers.

written

matches message if it has been saved without its headers.

new

recent

matches message if it is new. Two names for one selector.

read

matches message if it is neither new nor unread.

unread

unseen

matches message if it is not new and hasn’t been read. Two names for one selector.

flagged

matches message if it is flagged (see Message Attributes).

unflagged

matches message if it is not flagged.

replied

answered

matches message if it has been replied to. Two names for one selector.

unreplied

unanswered

matches message if it has not been replied to. Two names for one selector.

forwarded

matches message if it has been forwarded using a variant of vm-forward-message, vm-send-digest or one of their variants.

unforwarded

matches message if it has not been forwarded using vm-forward-message, vm-send-digest or one of their variants.

redistributed

matches message if it has been redistributed using vm-resend-message.

unredistributed

matches message if it has not been redistributed using vm-resend-message.

marked

matches message if it is marked, as with vm-mark-message.

unmarked

matches message if it is not marked.

selected

matches the message the folder is looking at, and no other.

unwritten

matches message if it has not been saved without its headers.

label

matches message if ARG is one of its labels (see Message Attributes). ARG is a label name, matched in full rather than as a regular expression, so ‘(label "todo")’ selects the messages labelled ‘todo’ and not those labelled ‘todo-later’. The command vm-create-label-virtual-folder (V l) is a short cut for using this selector interactively.

collapsed

matches message if it is the root of a thread that is currently collapsed in the summary (see Threading). Takes no ARG.

expanded

matches message if it is the root of a thread that is currently expanded in the summary. Takes no ARG.

Selectors based on analyzing the text ¶

attachment ¶

matches if a message contains an attachment, i.e., its text matches vm-vs-attachment-regexp.

spam-word

matches message if it contains one of the words listed in the file vm-spam-words-file. ARG says where to look, and is one of ‘header’, ‘text’ or ‘header-or-text’; it defaults to ‘header-or-text’. As with text, a message held in an external source must have been loaded for its body to be searched.

less-chars-than

matches message if message has less than ARG characters. ARG should be a number.

less-lines-than

matches message if message has less than ARG lines. ARG should be a number.

more-chars-than

matches message if message has more than ARG characters. ARG should be a number.

more-lines-than

matches message if message has more than ARG lines. ARG should be a number.

Complex selector operations ¶

sexp

matches message if the argument “s-expression” yields t. For example, to find all the messages from ‘Jenny’ with attachments, you can type V C sexp RET (and (author "Jenny") attachment) RET.

(This selector is available for creating interactive virtual folders. The argument “s-expression” can involve selectors combined using the logical connectives listed below. There would be no need to use the sexp selector in defining predefined virtual folders because those definitions can directly use “s-expressions”.)

eval

matches message if evaluating the Lisp expression ARG yields t. The Lisp expression can refer to the message by the name vm-virtual-message. This is more flexible than the sexp selector because it allows arbitrary Lisp expressions, not only the built-in selectors. However, you would need some knowledge of the Lisp functions that manipulate VM messages to use this selector.

and

matches the message if all its argument selectors match the message. Example:

(and (author "Derek McGinty") (new))

matches all new messages from Derek McGinty. and takes any number of arguments.

not

matches message only if its selector argument does NOT match the message. Example:

(not (deleted))

matches messages that are not deleted.

or

matches the message if any of its argument selectors match the message. Example:

(or (author "Dave Weckl") (subject "drum"))

matches messages from Dave Weckl or messages with the string “drum” in their Subject header. or takes any number of arguments.

thread

matches a message thread if any message in the thread matches the argument selector. Example:

(thread (outgoing))

matches all threads that have an outgoing message, i.e., a message authored by you.

thread-all

matches a message thread if all messages in the thread match the argument selector. Example:

(thread (less-chars-than 1000))

matches threads if all their messages contain fewer than 1000 characters.

Selectors based on context ¶

folder-name

matches message if it is from a folder matching ARG

virtual-folder-member

matches message if the message is already a member of some virtual folder currently being visited.

vm-mode

matches the message if the current-buffer is in vm-mode and one of its argument selectors matches the message.

mail-mode

matches the message if the current-buffer is in mail-mode and one of its argument selectors matches the message.

Automatic deletion ¶

Automatic deletion of messages based on the virtual folder facility can be achieved with the command vm-virtual-auto-delete-message (bound to V D in version 8). First, set the variable vm-virtual-auto-delete-message-selector to the name of a virtual folder whose members should be normally deleted. Then invoking the command on the current message (or a COUNT number of messages with a prefix argument) deletes all those messages among them that belong to the virtual folder vm-virtual-auto-delete-message-selector. There is no need to separately view the virtual folder before deleting such messages.

Command: vm-virtual-auto-delete-messages ¶

Mark all messages from the current up to the last for (spam-)deletion. Add this to vm-arrived-messages-hook.

See the function vm-virtual-auto-delete-message for details.

(add-hook ’vm-arrived-messages-hook #’vm-virtual-auto-delete-messages)

Add it to vm-arrived-messages-hook and the messages it matches are deleted before you ever see them.

Automatic saving ¶

The commands M-x vm-virtual-save-message and M-x vm-virtual-auto-archive-messages provide variants of vm-save-message and vm-auto-archive-messages based on the virtual folder facility. To use them, you must first set the variable vm-virtual-auto-folder-alist to an association-list of the form

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

where VIRTUAL-FOLDER-NAME is a string and FOLDER is either a string or an expression that evaluates to a string. If the message being saved is a member of VIRTUAL-FOLDER-NAME, as per its definition in vm-virtual-folder-alist, then FOLDER is regarded as the place where it should be saved. The command vm-virtual-save-message suggests this folder as the default location for saving. The command vm-virtual-auto-archive-messages archives all matching messages in the corresponding FOLDERs, as suggested by vm-virtual-auto-folder-alist.

Automatic filtering ¶

Automatic deletion applies one action list to one selector. The variable vm-virtual-filter-alist is a table of them, so that different kinds of incoming mail can be treated differently. Its value is an association-list of the form

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

where VIRTUAL-FOLDER-NAME names a virtual folder in vm-virtual-folder-alist, whose selector says which messages the rule applies to, and ACTIONS is a property list saying what to do with them:

:label STRING

Attach the labels named in STRING, a space separated list, as vm-add-message-labels takes them.

:attributes STRING

Set the attributes named in STRING, a space separated list, as vm-set-message-attributes takes them.

:save FOLDER

Save a copy of the message in FOLDER, which is a string or an expression evaluating to one.

:skip-inbox t

Keep the message out of the folder. It is flagged deleted and expunged once every rule has run.

Every rule whose selector matches is applied, in the order they appear, so one message can be labelled by one rule and saved by another. A rule naming a virtual folder that does not exist is an error rather than a rule that matches nothing.

Add vm-virtual-filter-new-messages to vm-arrived-messages-hook to have the rules applied to incoming mail:

(setq vm-virtual-folder-alist
      '(("from-arik" (("inbox") (author "arik")))
        ("spam"      (("inbox") (spam-word)))))
(setq vm-virtual-filter-alist
      '(("from-arik" :label "arik" :attributes "read")
        ("spam"      :save "spam-folder" :skip-inbox t)))
(add-hook 'vm-arrived-messages-hook #'vm-virtual-filter-new-messages)

Messages are written into the folder before any arrival hook runs, so :skip-inbox removes a message again rather than preventing its arrival. The command M-x vm-virtual-filter-messages applies the same table to the current message, or to a COUNT of them with a prefix argument, which is a convenient way to test a table before hooking it up.