My first mutt A quick beginners guide for anybody adopting the mutt mailer

Mail accounts

Where does your mail actually live?

This guide was written when a Unix machine received its own mail: messages were delivered over SMTP to a local mailspool, and mutt simply read the file. That still works, and if it describes your setup you can skip this page.

For nearly everybody else, mail lives on somebody else’s IMAP server - Gmail, Microsoft 365, Fastmail, Proton, a university, a hosting company. So the first job is connecting mutt to that account. There are two ways to do it, and you can change your mind later:

Start with the direct connection. It is five lines of configuration and you will learn what your provider expects.

Talking to IMAP directly

Put something like this in your ~/.muttrc :

set imap_user = "you@example.com"
set folder    = "imaps://imap.example.com/"
set spoolfile = "+INBOX"
set smtp_url  = "smtps://you@example.com@smtp.example.com/"
set from      = "you@example.com"
set realname  = "Your Name"

Your provider’s help pages will give you the server names. Mutt addresses all three of its network protocols with the same URL form:

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

proto is imap , pop or smtp , and appending an s asks for an encrypted connection. So there are six schemes you might meet - imap and imaps , pop and pops , smtp and smtps - and you want the s form every time. Mutt will refuse to talk to a remote server in the clear anyway, which is the ssl_force_tls setting; leave it alone, and if you find advice telling you to unset it, that advice is old.

Two things that catch people out:

Leave the port off and mutt uses the standard one for the protocol. The full rules, including which characters need %-encoding in a username, are in the URL syntax section of the manual.

Passwords

You can put set imap_pass="secret" in your muttrc, and you should not: it is a plain-text password sitting in a file that gets copied around and backed up.

The usual approach is to keep the secret encrypted and have mutt decrypt it at startup. Put your settings in a separate file, encrypt it with gpg, and source the output:

source "gpg --batch -dq ~/.mutt/account.gpg |"

Anything gpg prints becomes mutt configuration, so that file holds your set imap_pass and set smtp_pass lines. You will be asked for your gpg passphrase once when mutt starts. The same trick works with pass , secret-tool or any other password manager that will print a secret to standard output. See the manual’s notes on passwords for what this does and does not protect you from.

App passwords

Most large providers no longer accept your ordinary account password from a mail client, particularly once two-factor authentication is switched on. Instead you generate an app password : a long random string, created in your account’s security settings, used by one program only, and revocable on its own.

If your provider offers app passwords, use one. It needs no special support in mutt - it is just a password, stored as above - and it is the shortest path to a working setup.

OAuth2

Some providers, notably Microsoft 365 in many corporate configurations, have withdrawn app passwords and will only accept OAuth2 bearer tokens. Mutt supports this: it calls an external command to fetch a current token and hands it to the server.

Mutt ships a script that does the fetching, contrib/mutt_oauth2.py , installed as /usr/share/doc/mutt/mutt_oauth2.py on most systems. It knows about Google and Microsoft. Edit the top of the script to name your gpg identity, then authorize it once:

mutt_oauth2.py you@example.com.tokens --verbose --authorize
mutt_oauth2.py you@example.com.tokens --verbose --test

After which the muttrc side looks like this:

set imap_user             = "you@example.com"
set folder                = "imaps://outlook.office365.com/"
set smtp_url              = "smtp://${imap_user}@smtp.office365.com:587/"
set imap_authenticators   = "oauthbearer:xoauth2"
set imap_oauth_refresh_command = "/usr/share/doc/mutt/mutt_oauth2.py ${imap_user}.tokens"
set smtp_authenticators   = ${imap_authenticators}
set smtp_oauth_refresh_command = ${imap_oauth_refresh_command}

The token store is encrypted because the tokens in it are usable on their own. Read mutt_oauth2.py.README alongside the script; it explains the whole business clearly, including what to do when your organisation will not register the client. The OAUTHBEARER section of the manual has the reference detail.

If you are syncing to a local Maildir instead, mbsync and getmail6 have their own equivalent settings, and can generally be pointed at the same token script.

More than one account

Use account-hook to change credentials as mutt connects to each server, and folder-hook to change your identity as you move between mailboxes:

account-hook imaps://imap.example.com/ 'set imap_user=you@example.com'
account-hook imaps://imap.work.example/ 'set imap_user=you@work.example'

folder-hook imaps://imap.work.example/ 'set from=you@work.example; set smtp_url=...'

Tell mutt which addresses are yours so that it does the right thing on group replies:

alternates "^(you@example\.com|you@work\.example)$"

There is a worked example of a multiple-account setup in the manual.

When it doesn’t work

Last updated 31 August 2026.