Mutt quick-start


The whole time at the university, I used macOS for everything. When I started working for my first employer, I was given a company notebook. All of internal tools were designed to work on Linux, so it was easy choice to install my preferred distro (Debian) and start working.

Ouch. For a long time I was used to interact with various Linux servers via ssh, which is where Linux is super powered. But now, after about five years, I sat before a Linux desktop and I suffered from the poor UI experience.

What I missed probably the most was user friendly Mail client, something as simple and intuitive as the Mail app on macOS.

I tried many different applications including the most popular Thunderbird, but I was not satisfied. I remembered a friend from university, that showed me the mutt email client.


The mutt is a terminal based MUA (Mail User Agent). It has no graphical UI and it is completely controlled by keyboard shortcuts. As with all similar tools, it is super powerful, but the learning curve is steep1.

The reason for this post is that I didn’t find many useful quick-start guides. This post should explain basic concepts and help you set up the mutt mail client for simple usage.

The official documentation is mostly very explanatory, but it’s not going to help you if you don’t know what are you looking for.

How email actually works

Every email client has two main responsibilities. Sending emails and browsing emails. Each of these two jobs is done via special protocol.

Sending emails is done via protocol called SMTP. This protocol is really ancient, and has received many extensions since its launch in the year 1971. In the SMTP scenario, your MUA is the client and you need to tell it where to find the server and how to authenticate.

Browsing emails is now almost exclusively done via the IMAP protocol. Note that we don’t talk about RECEIVING emails. Email is received by your email server, and your MUA is used only to browse the received emails. As with email, your mail application (MUA) needs to know the IMAP server address and authentication information, usually username and password.

Note that IMAP server and SMTP server can be two totally different machines. As such, the SMTP and IMAP credentials does not have to be identical, although it is the most common setup.

Modes of operation

To configure mutt, you must understand the basic modes in which it can operate. This chapter is only very brief introduction, for more thorough explanation, please refer to the official newbie guide

Let’s start with the one that was added later. This mode makes mutt operate mostly like any other email client you are used to. This means you just provide SMTP and IMAP information and the email client itself connects to the servers and provides you with streamlined experience. This is somewhat easy to set up, but it does not align well with the UNIX philosophy of small tools doing one thing and doing it well.

The mutt must have both SMTP and IMAP protocols implemented, which, especially in the case of IMAP, is a lot of complex code.

This brings us to the second mode, in which we use external programs to do the client-server interaction. We use specialized IMAP client (such as offlineimap) to take care of downloading the received email to our local storage. The email is stored in a well defined format (mbox(5) or Maildir). Mutt (or other email client) then presents the local copy of emails to the user. When the user decides to send an email, mutt pipes the email content to another external application (such as msmtp) which takes care of delivering the message to the SMTP server.

In case we decide to go the second way, we are condemned to set up three different tools, using three different config file formats and so on.

As of 2022, I personally see these main benefits of going with the separated scenario:

  1. Using offlineimap (or similar), I get full offline copy of all my emails. This gives you much more seamless experience, as you don’t have to wait for the whole mailbox to download. And it also provides you with free backup of your emails. This is generally very underestimated, but imagine that you lost access to all your emails. If you use let’s say Gmail, it’s unlikely that the whole company disappears overnight, but on the other hand there is certain probability that your account will be blocked for some reason. Also real life happens, Google engineers can make mistake and your mailbox will be gone.
  2. Using external SMTP client. This one is harder to advocate. The main (and only) benefit that I found so far is that you may use the msmtp also from other applications. This is however rare, and you might not find it worth the added config. My only use-case so far was git format-patch | msmtp.

User interface

When you start mutt for the first time, you will be presented with the following screen.

Empty interface of mutt without any configuration

This screen is called index in mutt terminology and it will show you list of your emails, once you point it to some folder. The top bar suggests you a few actions that you might achieve. The letter before : is the key to which an action is bound. By pressing ? you therefore invoke a help screen. The help screen will present you plenty of functions, of which you will first only need few.

Help preview for index

Note that navigating in the interface is anything but intuitive, if you are used to let’s say vim (as I am). The key bindings can be adjusted and we will do it later on. The bottom bar informs you that you are in the Help content for index screen. Notice that you can press ? once more. This time, you will get Help for the screen pager, because the help contents is presented in the pager screen.

You can get a list of different screens here in the official documentation.

Easy setup for browsing emails

Mutt is configured via a configuration file. You can either point mutt to specific file by running mutt -F <config file>, or if you don’t the default used will be ~/.muttrc.

The configuration file is used to set variables (mostly) which control the behaviour of mutt. Note that you can also set the variables interactively when mutt is running. You can again refer to the official guide for more information.

# Minimal .muttrc file, that points mutt to your remote mailbox
set folder="imaps://"
# The spoolfile variable points to the folder with your incoming email.
# This is usually INBOX, but it depends on you email server settings
# The + sign gets expanded to the content of variable $folder (see Mailbox shortcuts in documentation)
set spoolfile="+INBOX"

The above configuration file should cause, that the next time you open mutt, you will be asked for your IMAP password. When you enter the password, the content of your inbox will be downloaded. This can take some time, depending on the content of your inbox.

Non empty interface

Sending emails

Now when you know how to browse your messages, you’d certainly like to send some. We will extend the .muttrc file with settings for sending emails. None of them is technically required, because mutt uses the sendmail(1) program for delivery by default. This can work, but also must not. With the complexity of today’s anti-spam filters and especially SPF, it’s very likely that your email will be rejected by the recipient’s server. For the purpose of sending emails inside some company intranet this might be sufficient, but it won’t provide you with reliable behaviour for the outer world communication.

This is why you have to setup an SMTP server, your name and email address.

# Adjust to your needs
set smtp_url="smtp://"
# Your real name
set realname = "Example User"
# Email address used as sender
set from = ""

The only missing thing here is the smtp password, which we don’t store in a plain-text file for security reasons. Now mutt will ask you for the password, when you sent an email.

To compose new email, press the m key (bound to function “mail”). Now the prompt in the last line asks you for recipient (fill and confirm) and for Subject (fill and confirm). After this, your preferred editor ($VISUAL ) launches and you can start composing an email.

Compose menu screen. You can see headers, attachments and other information about the message. The used color scheme is Gruvbox

When you are satisfied with the result, save the content of editor (:wq in vim). Then you’ll see a screen called Compose Menu. From here, you can reopen the editor (press e ), edit Cc: field (press c ) or send the email (press y ).


What was described in this article, should help you to perform minimal setup of the mutt program. This setup does not contain customized keybindings (such as those from vi), performance optimizations (such as header cache), security improvements (such as GPG integration) nor UI improvements (such as custom color scheme2). It is only emergency setup intended for the case when you need a mail client on Linux box fast. Other improvements can always be added one by one, depending on your personal preferences.

You can spend utter amount of time configuring the application, but you will be rewarded by fast, intuitive, portable (and maybe even visually pleasing) experience.

  1. This means it takes long time to learn, which is a bit counter intuitive. If you draw the learning curve as understanding as a function of time, steep learning curve is the one where learning is easy and fast. But hey, it’s commonly used this way. ↩︎

  2. I like the Gruvbox color scheme very much ↩︎