<insert dog metaphor here> Using Mutt Part 1: Getting Started

by Kyle Rankin

Related link: http://www.mutt.org

So I've written about mutt a few times before, but for the most part I've jumped ahead into advanced usage. Since I've recently gotten a few beginner-level mutt questions, I've decided to devote a few blog entries to mutt basics.

In case you haven't heard of mutt, it's a text-based mail client along the lines of pine or elm. Mutt is known for being a fast and highly configurable mail client, and since it's text-based, it's ideal for checking email quickly over ssh.

In this entry I'm just going to talk about a standard no-frills mutt config and some basic tips on how to use mutt. I'm going to focus on accessing IMAP folders since that seems to be the most common way people access their email these days (and one of the most common ways people get tripped up with mutt). Also notice I've set myself up for a multi-part blog entry, this way I'm forced to follow-up with a bit more advanced usage since if you stop here, you'll miss out on a lot of great things about mutt.

(Note: About halfway through writing this entry, I noticed that another introduction to mutt article was posted at http://www.linux.com/article.pl?sid=05/10/07/172259. That article mostly covers using fetchmail and POP with mutt, which I wasn't planning on talking about anyway, so if you use POP check out that article for POP-specific info.)

Why Use Mutt?

There are many different email clients out there, so what is it about mutt that so many people like? Well, there are a few things:

  • Mutt is fast

    One of the advantages of being a text-based email client is that mutt is lightweight and performs a lot faster than other clients when reading through email. The fact that you only use the keyboard with mutt also means that after you get down the initial keybindings for things, you can really quickly blast through all of your new mail.

  • Mutt is configurable

    Basically every mutt default can be changed. Anything from keybindings to which email headers it displays to when to use PGP and when not to can be configured.

  • Mutt is vim-like by default

    Okay, maybe this is just a feature to me, but many of the keybindings and general behavior of mutt follow vim conventions. And just in case you don't like vim's conventions, like I said, it's configurable so you can change it.

  • Mutt can be accessed remotely

    Since mutt is a text-based browser, no matter what computer you are in front of, you can ssh to one of your own computers that has mutt and check up on your email quickly--even over a dialup connection.

  • Mutt has hooks

    While I won't get into hooks in this entry, mutt hooks basically let you tie settings or functions to an attribute of an email or an email folder. For instance, you can easily set up multiple signatures and use mutt's send-hook feature to bind one signature and FROM address to your friends and family, and one signature and FROM address to your clients. You can also use the save-hook feature to automatically set the default saved message folder for an email based on the contents of that email.

Install Mutt

I'm not going to go into great detail on how to install mutt, since it will vary depending on what Linux distribution, or OS you are installing it on. It's a popular-enough program that your distribution or OS should at least have the "stable" mutt series (1.4) but if you can, you should try to track down a packaged version of the "development" series (1.5.*) if you use IMAP for the single reason that it uses header caching (more on that below). Install mutt using your OS's package management tool, or you can always download the source from http://www.mutt.org and compile it yourself. In either case, once you are finished it's time for the initial configuration.

Configure Mutt

Okay here is where things get interesting. One of the nicest features of mutt is how configurable it is, but the downside of all that configurability is that there are lots of options for the beginner to choose from. Mutt doesn't use an interactive tool for configuration, instead it expects a ~/.muttrc file containing all of your options. In another part of this series I may cover my personal methodology for managing mutt options, but for now what's important is a limited-frills general-purpose ~/.muttrc file that will let you check your mail on an IMAPS server.

I'm going to split this off into a few parts so I can talk about each part, but if you wanted all of these settings you would open up a text editor, paste it all in, and save it as ~/.muttrc. The first part contains some basic foundation settings:

set folder=imaps://imap.example.com/ # Point to IMAP server
set imap_user=jmuttley # Your IMAP username
set imap_pass=password # Your IMAP password. This is in plain text!
set spoolfile=+INBOX # Your main mailbox
set from="Joe Muttley <joe@example.com>" # Default address for outgoing mail

set copy=yes # Whether to save sent messages
set record=+Sent # Where to save sent messages
set beep_new=yes # Beep when new messages arrive?
set move=no # Move read messages to another folder?
set forward_quote=yes # Quote the email body when forwarding?
set include=yes # Quote the email body when replying?
ignore * # this means "ignore all headers by default"
# I do want to see these fields, though
unignore date from subject to cc

The above settings are enough to get you started so you can check your IMAP share INBOX. In fact some of these settings aren't even really necessary, but they set up some decent defaults (or at least expose them so you can change them easily). The first two lines configure my default "folder" (or in this case my IMAP server) and my IMAP user, respectively. Note that if you do specify your IMAP password, it will be in plain text in this file. If you don't want that, remove that line and mutt will just prompt you for your password when you connect to the IMAP server. In the example I use imaps, but change that to imap if you don't want to use IMAPS.

SMTP support (or lack thereof)

Note that I didn't configure any sort of SMTP server. Unlike most other mail clients, mutt is strictly a mail user agent and doesn't contain code to communicate directly with an SMTP server. Mutt hands off the mail to the mail delivery system on your local machine, so you need to make sure that it is configured properly so that you can send mail using the "mail" command. This is a common thing that trips up new mutt users, as most people are used to the mail client talking directly to a mail server using SMTP.

Non-essential (but Useful) Settings

Next I'll cover some less essential settings that I still think are worth mentioning and adding to your .muttrc file. Most of these are commented but reference mutt's documentation page if you want more information on any of these settings.

I like to create a ~/.mutt directory where I store all of mutt's other configuration files such as my signatures and the alias list (so you can email "fred" and fred's full email address will be filled in for you). You'll see how I reference that in the config below. Also I've added a number of other settings that I like using or that I think are important to at least highlight in case you want to change them:

set alias_file="~/.mutt/aliases"
source ~/.mutt/aliases
set signature="~/.mutt/sig"
set sig_on_top # Don't do this on mailing lists!
set mail_check=90 # check for new mail every 90 seconds
set timeout=15 # after 15 secs of no keypresses, start checking for new mail
set reverse_name # Reply with the address used in the TO/CC header
set ascii_chars=yes # Use ASCII arrows
set reverse_realname=yes # Reply with the name used in FROM
set reverse_alias=yes
set fast_reply="yes"
set confirmappend=no # Confirm when appending messages to an existing mailbox?
set pager_index_lines=5 # Show 5 message headers from your message index above an email you are reading
# h will take you to the folder list in the index
macro index h "c?\t"

# VIM with special startup settings
set editor="vim -c 'set nohlsearch noshowmatch modelines=0 tw=75 et noai'"

I should probably explain that last line in more detail. Mutt by default uses VIM as its text editor when you write an email. That last configuration option lets me configure the program that mutt launches when editing an email and in that case it launches mutt with a number of options that are suitable for writing emails. You could also use this option to change the editor from vim to whatever console text editor you prefer to use.

IMAP Folders

With the above config, by default mutt will only check your INBOX for new mail. You can hit the 'h' key (due to the macro I added) to access the list of mailboxes, but you will have to hit the tab key to see them all. What is better is to configure mutt with all of the mailboxes you want to be able to check with the mailboxes configuration option.

Each mailbox added to mutt will be automatically checked for new mail, and when there is new mail, mutt will give precedence to a folder based on the order you specify them. When you hit 'c' to change to another folder (more on the keybindings and how to use mutt below), mutt will automatically fill in the name of the next folder in the list that contains new mail. I like this feature since I can quickly go through all of my "important" folders first followed by the less-important folders.

Say you want to add three folders: Work, Friends, and SPAM in that order, you would add the following three lines to your .muttrc:

mailboxes "=Work"
mailboxes "=Friends"
mailboxes "=SPAM"

Header Caching

One of the best new features in the development version of mutt (and mutt-ng, which I mention here) is header caching. If you use IMAP and have folders with lots of messages, it can be annoying to have to sit while mutt downloads every header each time, even though mutt does it relatively quickly. Header caching makes mutt behave like a lot of other mail clients and it caches the headers it already has downloaded locally so it only needs to retrieve new email headers. This results in a big boost in speed when opening new folders and if you use mutt and IMAP I highly recommend getting the mutt development version just for this feature.

Header caching isn't enabled by default, so to enable it you will need to create a new directory on your machine to store headers (I made one called ~/.muttheaders) and then add the following line to your ~/.muttrc:

set header_cache="~/.muttheaders"

Using Mutt

Now that mutt is configured, it's time to start it up. I'm going to go over some of the basic keybindings you will use to navigate through mutt, but this is far from an exhaustive list. To start mutt, open a terminal and type mutt.

Navigate the message index

Mutt by default will open up into your main mailbox file, which should be configured to be your INBOX. You can use the arrow keys or j and k to move up and down through the list of messages (which mutt calls the "index"). The Tab key will take you to the next New message in the index. In this mode you can hit 'n' to make a message as new, 'd' to delete a message, or 'u' to undelete a message.

If you use the key macro I added above, you can hit the 'h' key and mutt will take you to a the folder view where you can view any configured mailboxes. Highlight one and hit Enter to change to it.

Read a Message

To read a message, highlight it and hit Enter. You can page forward through the message one line at a time with the enter key and backwards with the backspace key. Pgdn and Pgup will let you move down and up a message one page at a time. If you want to reply to or forward the message, hit 'r' or 'f' respectively. If you want to return to the message index, hit 'q'.

Compose a Message

To compose a message, hit the 'm' key. Mutt will prompt you for the address to mail to, the subject, and then will launch the text editor of your choice (vim by default) to edit your message. When you are finished typing your message, save it and close the editor. Mutt will then take you to a screen where you can add CC, BCC, or edit the To or From headers of the message. In this mode hit 'a' to add attachments. If you want to go edit your message again, highlight it and hit 'e'. When you are ready to send the email, hit 'y', or otherwise hit 'q' to exit. If you exit in the middle of a message, mutt will prompt you to postpone it for later if you want. The next time you hit 'm' to compose a message, mutt will prompt you for whether you want to open the postponed message.

Get Help

If you can't remember a particular keybindings, just hit ? to open into the mutt help screen. To go back to where you were, hit 'q'.

Exit Mutt

When you are finished using mutt, hit 'q' in the message index to leave, or otherwise hit 'x' to immediately close the program without saving any unsaved changes.

How I Check My Mail

Here's a quick overview of a normal mail-checking session of mine using mutt. I start mutt, and hit Tab if I'm not automatically over the next New message. I then hit Enter, read the message, and without hitting 'q', I hit Tab to skip ahead to the next message. I do this until there aren't any more new messages in this particular folder. Then I hit 'c' to show me whether there are any other folders with new mail and hit Enter to change to that folder. Then I hit Enter to open the first new message in that folder and then Tab through that folder of messages. I repeat these steps for any other folders with new mail. Once you get the hang of it, you can go through all of your mail really rapidly this way.


This is far from an full explanation of how to use mutt effectively. I hope in the next part to talk more about how I personally use mutt to blast through my email. I may also cover some of mutt's hook settings and how I organize my mutt settings.

Do you have any other beginner-level tips for new mutt users? Post them here.