Configuring mutt or neomutt with IMAP and SMTP

mutt and neomutt are terminal mail clients that can use IMAP and SMTP directly. This guide sets up one account with TLS on both servers. The password is never written into the configuration file. Mutt reads it at runtime from a command, so the secret stays in your password manager or keyring.

Step 1: Create an app password

Create an app password in the webmail under Account, then Security. Label it for this machine, for example "mutt workstation". Copy it once, then store it in your password store.

Step 2: Store the app password in pass

With the pass password manager, insert the secret under a path that names the account:

pass insert itpromail/jane@example.com

Paste the app password as the first line. Anything after the first line is ignored by the configuration below.

On macOS, you can use the Keychain instead. Store the app password with security add-generic-password -s itpromail -a jane@example.com -w and read it back with security find-generic-password -s itpromail -w in place of the pass command.

Step 3: Write the muttrc

Create ~/.config/mutt/muttrc (or ~/.config/neomutt/neomuttrc for neomutt) with the following. Replace the example address and name with your own.

set realname = "Jane Example"
set from = "jane@example.com"
set use_from = yes

set imap_user = "jane@example.com"
set imap_pass = `pass show itpromail/jane@example.com | head -n 1`
set folder = "imaps://imap.itpromail.com:993/"
set spoolfile = "+INBOX"
set record = "+Sent"
set postponed = "+Drafts"

set smtp_url = "smtps://jane%40example.com@smtp.itpromail.com:465/"
set smtp_pass = `pass show itpromail/jane@example.com | head -n 1`

set ssl_force_tls = yes
set ssl_verify_host = yes
set header_cache = "~/.cache/mutt"
set mail_check = 60

Backtick expansion runs the command when mutt starts and uses its output as the value. The head -n 1 keeps only the first line of the pass entry. The %40 in the SMTP URL is the encoded form of the @ in the username, which the URL syntax requires.

Using STARTTLS for SMTP

If port 465 is blocked, change the outgoing line to use port 587 and the plain smtp:// scheme. Mutt negotiates STARTTLS on that port, and ssl_force_tls makes it refuse to continue without encryption:

set smtp_url = "smtp://jane%40example.com@smtp.itpromail.com:587/"

Folder names

The +Sent, +Drafts and +INBOX values must match the folder names on the server. Open mutt and press c to change folder, then ? to list them. If a folder name differs, correct the value in the muttrc.

Testing

Start mutt and confirm the inbox opens. Send a message to an address you control, then check that a copy appears in the Sent folder both locally and in the webmail. If sending fails with an authentication error, check that the pass entry contains the app password and not the account password.

Keeping the configuration safe

The muttrc contains no secrets, so it can be kept in version control or a dotfiles repository. Keep the pass store itself protected with a GPG key and a passphrase. Revoke the app password from Account, then Security if the machine is lost.

For the full server reference, see IMAP and SMTP settings.