These notes describe IMAP facilities present in mutt 1.4 and later.

1. Getting started

1.1. How to write an IMAP mailbox in mutt

To point mutt to an IMAP mailbox, write your mailbox in IMAP URL format:

imap://hostname/mailbox

where hostname is the name of your IMAP server, and mailbox is the name of your mailbox on the server. All IMAP servers provide one special folder called INBOX, which is where your incoming mail normally arrives. For example, if your IMAP server is mailhost.mydomain.com, you could open your INBOX there by telling mutt to open imap://mailhost.mydomain.com/INBOX

If necessary, you can also specify the port your IMAP server listens on, and ask mutt to use ssl if available. The full form of an IMAP mailbox in mutt is

imap[s]://[user@]hostname[:port]/mailbox

Mutt also understands PINE-compatible IMAP mailbox notation:

{[user@]hostname[:port][/ssl]}mailbox

1.1.1. What about the mailbox part?

How you write the actually mailbox name may depend on your IMAP server. First, some servers will put all of your mail into a subfolder, often a subfolder of INBOX. For instance, if your server is Courier or Cyrus, your folder Lists may actually be INBOX.Lists. This brings us to point number two: some servers don't use '/' to separate folder names. The reference server (UW-IMAP) uses '/', but two common servers (Courier and Cyrus) both generally use '.', and Lotus Notes has a server which uses '\' (a very bad choice, by the way). Generally you can use '/' and mutt will figure out what to do with it, though. Some examples:

imap://hostname/lists/mutt-dev imap://hostname/INBOX.lists.mutt-dev

When mutt has proper namespace support, you will hopefully no longer have to worry about either of these issues.

1.2. Connecting to your IMAP server

To connect to your IMAP server, just switch to an IMAP mailbox. That is, press c to get the Open mailbox: prompt, and enter an IMAP mailbox as described above. You'll need your IMAP user name and password. You may set these in advance via configuration the variables imap_user and imap_pass. If you haven't set them, mutt will prompt you for this information when you first connect to your server.

1.2.1. Connection security

Mutt has advanced support for IMAP session security - probably as advanced as any other IMAP client, and more than most.

Mutt can encrypt your entire session using SSL, TLS or a SASL protection layer.
Mutt also knows about several authentication methods which don't send your password across the network: it has native support for CRAM-MD5 and GSSAPI (Kerberos) authentication, and if compiled with the Cyrus SASL library it can support numerous other methods (and more can be added by upgrading your SASL library, without recompiling mutt!).
Mutt supports a tunneling driver which allows you to connect using, eg, an SSH pipe which invokes your IMAP server directly on the remote machine.
Finally, you can specify a shell command to be run before every connection attempt, which may for instance use SSH to set up encrypted port-forwarding between mutt and the IMAP server.

1.2.1.1. SSL/TLS

To use SSL, specify your IMAP mailbox starting with imaps: instead of imap:. Mutt also supports TLS, which means that if your server does too, you can negotiate SSL over a normal IMAP connection (using imap:). Whether or not this happens depends on the mutt quadoption ssl_starttls, which defaults to ask-yes, meaning that if, and only if, the server supports TLS, mutt will ask you whether it should encrypt the connection before authenticating.

Each time you connect to an IMAP server using SSL, mutt will check the server's certificate against its list of known-good certificates, if available. These certificates are stored in the file pointed to by the configuration variable certificate_file, which is unset by default. If mutt cannot find the server certificate in this file, the certificate will be displayed to you and you must decide whether to accept it or reject it (and if you accept it and have a certificate_file set, whether or not to save it permanently). If you reject the certificate your connection will be terminated. Note you may also place a signing certificate into this file, in which case mutt will automatically accept any certificate which has been signed by it.

Some servers do not fully support all SSL protocols, and may disconnect you during connection if mutt tries to use one they do not understand. You can disable certain protocols by unsetting one or more of the configuration variables ssl_use_sslv2, ssl_use_sslv3, or ssl_use_tlsv1.

For more information, see the README.SSL file included in the mutt distribution.

1.2.1.2. Authentication methods

Mutt supports several ways to authenticate to your IMAP server, including plain-old login, CRAM-MD5 (in which the server issues a one-time challeng string which you hash with your password and then send back. The server also hashes the string with your password and compares the result), and GSSAPI, which is Kerberos V authentication. Additionally mutt supports authentication using the Cyrus SASL library, and can even encrypt your session when using SASL, if the particular method being used supports it.

Mutt will generally pick the best available authentication method, but you may override its selection by setting the imap_authenticators configuration variable. This is a colon-delimited list of methods mutt may try, in the order it should try them. If any of these methods are available but fail, or none of them are available, mutt will fail to authenticate. For example, if you only want to use GSSAPI to authenticate, you could

set imap_authenticators="gssapi"

in which case mutt will only try gssapi, and if that fails or is unavailable (either because the server doesn't support it or you have no ticket-granting ticket), mutt will not log you in. Or you could try something like

set imap_authenticators="digest-md5:cram-md5"

in which case mutt would attempt DIGEST-MD5 if your SASL library and the server support it, otherwise CRAM-MD5.

1.2.1.3. Using a tunnel to your IMAP server

If you set the configuration variable tunnel, mutt will attempt to run it as a shell command and treat the process as a pipe to an IMAP server, instead of connecting through a normal network socket. Note that the hostname, port and SSL options are ignored when tunnel is set, they are used only to display the mailbox name.

Also note that your tunnel command has no way to interact with the terminal, so it can't, for example, ask you for a password. If you try to use an SSH tunnel with something like

set tunnel="ssh -q mailhost /usr/libexec/imapd"

you'd better make sure that you don't need a password, probably by using ssh-agent. Otherwise you are likely to get a "Broken pipe" error when SSH dies.

1.2.1.4. Running a shell command before connecting

If you set the configuration variable preconnect, mutt will attempt to run it as a shell command before connecting to your IMAP server. You can use this feature to set up SSH port forwarding between your computer and the IMAP server. For example, if you

set preconnect="ssh -f -q -L 1234:mailhost:143 mailhost sleep 5"

then an IMAP folder of imap://localhost:1234/ can be used to access imap://mailhost/ over a secure SSH connection.

1.3. Using an IMAP server instead of local mail

Tell mutt to use your IMAP INBOX as your $spoolfile: set spoolfile=imap://hostname/INBOX
Set your $folder to your IMAP root: set folder=imap://hostname/

1.3.1. Polling for new mail

This works the same as normal mail, with a couple of caveats. You add mailboxes you'd like to check for mail using the mailboxes command. If you've set your folder as above, you can do

mailboxes =lists/mutt-dev =lists/mutt-users

to poll for mail in imap://hostname/lists/mutt-dev and imap://hostname/lists/mutt-users.

The caveats:

Mutt will scan for new mail in all of your mailboxes every mail_check seconds. The default is 5 seconds, which will make mutt feel very sluggish if you have more than a couple of mailboxes defined. You'll like mutt better if you increase this to at least 60.
Mutt checks for mail in the current IMAP mailbox no more ofter than timeout seconds. The default is 600, which means you will only get notified about new mail in your current mailbox every 10 minutes. You may wish to lower this to something like 15.

Brendan Cully