Optional Features

1. General Notes

1.1. Enabling/Disabling Features

Mutt supports several of optional features which can be enabled or disabled at compile-time by giving the configure script certain arguments. These are listed in the Optional featuressection of the configure --help output.

Which features are enabled or disabled can later be determined from the output of mutt -v. If a compile option starts with +it is enabled and disabled if prefixed with -. For example, if Mutt was compiled using GnuTLS for encrypted communication instead of OpenSSL, mutt -vwould contain:

-USE_SSL_OPENSSL +USE_SSL_GNUTLS

1.2. Mutt Patches

Mutt may also be patchedto support smaller features. These patches should add a free-form string to the end Mutt's version string. Running mutt -vmight show:

patch-1.8.2.sidebar.20170421

1.3. URL Syntax

Mutt optionally supports the IMAP, POP3 and SMTP protocols which require to access servers using URLs. The canonical syntax for specifying URLs in Mutt is (an item enclosed in []means it is optional and may be omitted):

proto[s]://[username[:password]@]server[:port][/path]

proto is the communication protocol: imapfor IMAP, popfor POP3 and smtpfor SMTP. If sfor secure communicationis appended, Mutt will attempt to establish an encrypted communication using SSL or TLS.

Since all protocols supported by Mutt support/require authentication, login credentials may be specified in the URL. This has the advantage that multiple IMAP, POP3 or SMTP servers may be specified (which isn't possible using, for example, $imap_user). The username may contain the @symbol being used by many mail systems as part of the login name. The special characters /( %2F), :( %3A) and %( %25) have to be URL-encoded in usernames using the %-notation.

A password can be given, too but is not recommended if the URL is specified in a configuration file on disk.

If no port number is given, Mutt will use the system's default for the given protocol (usually consulting /etc/services).

The optional path is only relevant for IMAP and ignored elsewhere.

Example 6.1. URLs

pops://host/
imaps://user@host/INBOX/Sent
smtp://user@host:587/

2. SSL/TLS Support

If Mutt is compiled with IMAP, POP3 and/or SMTP support, it can also be compiled with support for SSL or TLS using either OpenSSL or GnuTLS ( by running the configure script with the --enable-ssl=... option for OpenSSL or --enable-gnutls=... for GnuTLS). Mutt can then attempt to encrypt communication with remote servers if these protocols are suffixed with sfor secure communication.

3. POP3 Support

If Mutt is compiled with POP3 support (by running the configure script with the --enable-pop flag), it has the ability to work with mailboxes located on a remote POP3 server and fetch mail for local browsing.

Remote POP3 servers can be accessed using URLs with the popprotocol for unencrypted and popsfor encrypted communication, see Section 1.3, “URL Syntax”for details.

Polling for new mail is more expensive over POP3 than locally. For this reason the frequency at which Mutt will check for mail remotely can be controlled by the $pop_checkintervalvariable, which defaults to every 60 seconds.

POP is read-only which doesn't allow for some features like editing messages or changing flags. However, using Section 7.1, “Header Caching”and Section 7.2, “Body Caching”Mutt simulates the new/old/read flags as well as flagged and replied. Mutt applies some logic on top of remote messages but cannot change them so that modifications of flags are lost when messages are downloaded from the POP server (either by Mutt or other tools).

Another way to access your POP3 mail is the <fetch-mail>function (default: G). It allows to connect to $pop_host, fetch all your new mail and place it in the local $spoolfile. After this point, Mutt runs exactly as if the mail had always been local.

Note

If you only need to fetch all messages to a local mailbox you should consider using a specialized program, such as fetchmail(1), getmail(1)or similar.

4. IMAP Support

If Mutt was compiled with IMAP support (by running the configure script with the --enable-imap flag), it has the ability to work with folders located on a remote IMAP server.

You can access the remote inbox by selecting the folder by its URL (see Section 1.3, “URL Syntax”for details) using the imapor imapsprotocol. Alternatively, a pine-compatible notation is also supported, i.e. {[username@]imapserver[:port][/ssl]}path/to/folder

Note that not all servers use /as the hierarchy separator. Mutt should correctly notice which separator is being used by the server and convert paths accordingly.

When browsing folders on an IMAP server, you can toggle whether to look at only the folders you are subscribed to, or all folders with the toggle-subscribed command. See also the $imap_list_subscribedvariable.

Polling for new mail on an IMAP server can cause noticeable delays. So, you'll want to carefully tune the $mail_checkand $timeoutvariables. Reasonable values are:

set mail_check=90
set timeout=15

with relatively good results even over slow modem lines.

Note

Note that if you are using mbox as the mail store on UW servers prior to v12.250, the server has been reported to disconnect a client if another client selects the same folder.

4.1. The IMAP Folder Browser

As of version 1.2, Mutt supports browsing mailboxes on an IMAP server. This is mostly the same as the local file browser, with the following differences:

  • In lieu of file permissions, Mutt displays the string IMAP, possibly followed by the symbol +, indicating that the entry contains both messages and subfolders. On Cyrus-like servers folders will often contain both messages and subfolders.

  • For the case where an entry can contain both messages and subfolders, the selection key (bound to enterby default) will choose to descend into the subfolder view. If you wish to view the messages in that folder, you must use view-fileinstead (bound to spaceby default).

  • You can create, delete and rename mailboxes with the <create-mailbox>, <delete-mailbox>, and <rename-mailbox>commands (default bindings: C, dand r, respectively). You may also <subscribe>and <unsubscribe>to mailboxes (normally these are bound to sand u, respectively).

4.2. Authentication

Mutt supports four authentication methods with IMAP servers: SASL, GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add NTLM authentication for you poor exchange users out there, but it has yet to be integrated into the main tree). There is also support for the pseudo-protocol ANONYMOUS, which allows you to log in to a public IMAP server without having an account. To use ANONYMOUS, simply make your username blank or anonymous.

SASL is a special super-authenticator, which selects among several protocols (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure method available on your host and the server. Using some of these methods (including DIGEST-MD5 and possibly GSSAPI), your entire session will be encrypted and invisible to those teeming network snoops. It is the best option if you have it. To use it, you must have the Cyrus SASL library installed on your system and compile Mutt with the --with-sasl flag.

Mutt will try whichever methods are compiled in and available on the server, in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.

There are a few variables which control authentication:

  • $imap_user- controls the username under which you request authentication on the IMAP server, for all authenticators. This is overridden by an explicit username in the mailbox path (i.e. by using a mailbox name of the form {user@host}).

  • $imap_pass- a password which you may preset, used by all authentication methods where a password is needed.

  • $imap_authenticators- a colon-delimited list of IMAP authentication methods to try, in the order you wish to try them. If specified, this overrides Mutt's default (attempt everything, in the order listed above).

5. SMTP Support

Besides supporting traditional mail delivery through a sendmail-compatible program, Mutt supports delivery through SMTP if it was configured and built with --enable-smtp.

If the configuration variable $smtp_urlis set, Mutt will contact the given SMTP server to deliver messages; if it is unset, Mutt will use the program specified by $sendmail.

For details on the URL syntax, please see Section 1.3, “URL Syntax”.

The built-in SMTP support supports encryption (the smtpsprotocol using SSL or TLS) as well as SMTP authentication using SASL. The authentication mechanisms for SASL are specified in $smtp_authenticatorsdefaulting to an empty list which makes Mutt try all available methods from most-secure to least-secure.

6. Managing Multiple Accounts

Usage:

account-hook regexp command

If you happen to have accounts on multiple IMAP, POP and/or SMTP servers, you may find managing all the authentication settings inconvenient and error-prone. The account-hook command may help. This hook works like folder-hook but is invoked whenever Mutt needs to access a remote mailbox (including inside the folder browser), not just when you open the mailbox. This includes (for example) polling for new mail, storing Fcc messages and saving messages to a folder. As a consequence, account-hook should only be used to set connection-related settings such as passwords or tunnel commands but not settings such as sender address or name (because in general it should be considered unpredictable which account-hook was last used).

Some examples:

account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/libexec/smtpd"'

To manage multiple accounts with, for example, different values of $recordor sender addresses, folder-hook has to be be used together with the mailboxes command.

Example 6.2. Managing multiple accounts

mailboxes imap://user@host1/INBOX
folder-hook imap://user@host1/ 'set folder=imap://host1/ ; set record=+INBOX/Sent'
mailboxes imap://user@host2/INBOX
folder-hook imap://user@host2/ 'set folder=imap://host2/ ; set record=+INBOX/Sent'

In example Example 6.2, “Managing multiple accounts”the folders are defined using mailboxes so Mutt polls them for new mail. Each folder-hook triggers when one mailbox below each IMAP account is opened and sets $folderto the account's root folder. Next, it sets $recordto the INBOX/Sent folder below the newly set $folder. Please notice that the value the + mailbox shortcutrefers to depends on the current value of $folderand therefore has to be set separately per account. Setting other values like $fromor $signatureis analogous to setting $record.

7. Local Caching

Mutt contains two types of local caching: (1) the so-called header cachingand (2) the so-called body cachingwhich are both described in this section.

Header caching is optional as it depends on external libraries, body caching is always enabled if Mutt is compiled with POP and/or IMAP support as these use it (body caching requires no external library).

7.1. Header Caching

Mutt provides optional support for caching message headers for the following types of folders: IMAP, POP, Maildir and MH. Header caching greatly speeds up opening large folders because for remote folders, headers usually only need to be downloaded once. For Maildir and MH, reading the headers from a single file is much faster than looking at possibly thousands of single files (since Maildir and MH use one file per message.)

Header caching can be enabled via the configure script and the --enable-hcache option. It's not turned on by default because external database libraries are required: one of tokyocabinet, kyotocabinet, qdbm, gdbm, lmdb or bdb must be present.

If enabled, $header_cachecan be used to either point to a file or a directory. If set to point to a file, one database file for all folders will be used (which may result in lower performance), but one file per folder if it points to a directory.

Additionally, $header_cache_backendcan be used to specify which backend to use. The list of available backends can be specified at configure time with a set of --with-<backend> options. Currently, the following backends are supported: tokyocabinet, kyotocabinet, qdbm, gdbm, bdb, lmdb.

7.2. Body Caching

Both cache methods can be combined using the same directory for storage (and for IMAP/POP even provide meaningful file names) which simplifies manual maintenance tasks.

In addition to caching message headers only, Mutt can also cache whole message bodies. This results in faster display of messages for POP and IMAP folders because messages usually have to be downloaded only once.

For configuration, the variable $message_cachedirmust point to a directory. There, Mutt will create a hierarchy of subdirectories named like the account and mailbox path the cache is for.

7.3. Cache Directories

For using both, header and body caching, $header_cacheand $message_cachedircan be safely set to the same value.

In a header or body cache directory, Mutt creates a directory hierarchy named like: proto:user@hostnamewhere protois either popor imap.Within there, for each folder, Mutt stores messages in single files and header caches in files with the .hcacheextension. All files can be removed as needed if the consumed disk space becomes an issue as Mutt will silently fetch missing items again. Pathnames are always stored in UTF-8 encoding.

For Maildir and MH, the header cache files are named after the MD5 checksum of the path.

7.4. Maintenance

Mutt does not (yet) support maintenance features for header cache database files so that files have to be removed in case they grow too big. It depends on the database library used for header caching whether disk space freed by removing messages is re-used.

For body caches, Mutt can keep the local cache in sync with the remote mailbox if the $message_cache_cleanvariable is set. Cleaning means to remove messages from the cache which are no longer present in the mailbox which only happens when other mail clients or instances of Mutt using a different body cache location delete messages (Mutt itself removes deleted messages from the cache when syncing a mailbox). As cleaning can take a noticeable amount of time, it should not be set in general but only occasionally.

8. Exact Address Generation

Mutt supports the Name <user@host>address syntax for reading and writing messages, the older user@host (Name)syntax is only supported when reading messages. The --enable-exact-address switch can be given to configure to build it with write-support for the latter syntax. EXACT_ADDRESSin the output of mutt -vindicates whether it's supported.

9. Sending Anonymous Messages via Mixmaster

You may also have compiled Mutt to co-operate with Mixmaster, an anonymous remailer. Mixmaster permits you to send your messages anonymously using a chain of remailers. Mixmaster support in Mutt is for mixmaster version 2.04 or later.

To use it, you'll have to obey certain restrictions. Most important, you cannot use the Ccand Bccheaders. To tell Mutt to use mixmaster, you have to select a remailer chain, using the mix function on the compose menu.

The chain selection screen is divided into two parts. In the (larger) upper part, you get a list of remailers you may use. In the lower part, you see the currently selected chain of remailers.

You can navigate in the chain using the <chain-prev>and <chain-next>functions, which are by default bound to the left and right arrows and to the hand lkeys (think vi keyboard bindings). To insert a remailer at the current chain position, use the <insert>function. To append a remailer behind the current chain position, use <select-entry>or <append>. You can also delete entries from the chain, using the corresponding function. Finally, to abandon your changes, leave the menu, or <accept>them pressing (by default) the Returnkey.

Note that different remailers do have different capabilities, indicated in the %c entry of the remailer menu lines (see $mix_entry_format). Most important is the middlemancapability, indicated by a capital M: This means that the remailer in question cannot be used as the final element of a chain, but will only forward messages to other mixmaster remailers. For details on the other capabilities, please have a look at the mixmaster documentation.