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:
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
Mutt also understands PINE-compatible IMAP mailbox notation:
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:
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
- 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 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.
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
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.
220.127.116.11. 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
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
in which case mutt would attempt DIGEST-MD5 if your SASL library
and the server support it, otherwise CRAM-MD5.
18.104.22.168. 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
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.
22.214.171.124. 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 your $folder to your IMAP root:
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
- 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.