Hack and /

Mutt is my favorite e-mail client and the one I use every day both professionally and personally. The greatest yet most challenging thing about mutt is how incredibly configurable it is. As you use a program, you might think “I wish it did X, Y or Z”, but in the case of mutt, most of the major settings you want to tweak are available for you to change. If you have used mutt for many years like I have, you find that you go through a few phases with your .muttrc (the main configuration file for mutt). When you start using mutt, you spend a lot of time just trying to figure out how to set up mutt to read your mail (usually with the help of someone else's .muttrc). After you get mutt working, the next phase involves tweaking more and more sophisticated options, such as folder hooks. Eventually though, your .muttrc is finely tuned just the way you like it, and you change it only rarely. These days, I usually change my .muttrc only to add a new mailbox.

What I realize is that no matter how great I might think mutt is, if someone else wants to give it a try for the first time, the learning curve is a bit intimidating. In past columns I've discussed advanced settings for mutt, but in this column, my goal is to walk you through the one thing that intimidates mutt users the most when they start out: mutt configuration. Hopefully, by the end of the column you will have a basic, functional mutt configuration you can use to check your e-mail.

These days, mutt should be available as a package for just about any major distribution, so I'm not going to cover how to install it—just use your package manager. If you are used to a regular, graphical e-mail client, two main things are different about mutt. For one, it is designed to run completely from a terminal controlled by your keyboard. Second, mutt is strictly a Mail User Agent (MUA) and not a Mail Transfer Agent (MTA). Most graphical e-mail clients not only can access and read your e-mail as a MUA, but they also know how to be an MTA (they can communicate with a mail server directly via SMTP to send out e-mail). Unlike those clients, mutt is strictly concerned with accessing and reading your mail, and it relies on a separate MTA. This means if your Linux system doesn't already have a mail server configured, you will need to set up a basic one. If you need some tips on how to do that, check out my “Make a Local Mutt Mail Server” column in the February 2010 issue.

Although you certainly can set up your mutt configuration any way you want (as long as the core config is in ~/.muttrc), because you are doing this for the first time, you might as well set up a system of configuration files instead of one giant .muttrc. Because mutt allows you to reference other configuration files from within the .muttrc, many mutt users organize their options into different files. What I like to do is separate the configuration into different categories stored under ~/.mutt. I also store my .muttrc file there with the ~/.muttrc file symlinked to it. Finally, I create a ~/.muttrc.local file that I use to store any options I want to keep local to this machine. These are options like whether to access a remote IMAP server versus a local maildir, or other such local settings. Now this may seem like a lot of work, but the point is that once you get your mutt configuration how you want it, you simply can rsync the ~/.mutt directory to the rest of your machines without wiping out any local settings.

I realize that no sample mutt config is going to please everyone, but here are some basic settings that I think should get you off to the right start. I've added comments to options where I feel they need extra explanation, but plenty of options are uncommented, so if you are curious about what an option does, the best resource is the official mutt documentation at mutt.org. Every now and then I find myself browsing through the documentation there just to look for some new (or new to me) options that I didn't know I couldn't live without.

First, let's look at my main ~/.mutt/.muttrc file. Remember that I actually create a symlink from this file to ~/.muttrc with:

ln -s ~/.mutt/.muttrc ~/.muttrc

Also, it may go without saying, but you need to create the ~/.mutt directory as well. Listing 1 shows a basic starter ~/.mutt/.muttrc.

# Various client settings
set query_command="lbdbq %s"
set copy
set beep_new
set ascii_chars=yes
set reverse_name
set move=no
unset mark_old
set forward_quote
set include
set fast_reply="yes"
set indent_str="> "
# Cache email headers and store them in .muttheaders/
set header_cache="~/.muttheaders/"

# All the emails mutt should consider as being from me. 
# In this example, foo@example.org and bar@example.org are set.
set alternates=((foo|bar)@example.org) 

ignore *	# this means "ignore all headers by default"
# I do want to see these fields, though~
unignore	date from subject to cc

# local settings
source ~/.muttrc.local

# Color settings
source ~/.mutt/colors

# Where to store email aliases for people I email
set alias_file=~/.mutt/aliases
source ~/.mutt/aliases

# My list of mailboxes
source ~/.mutt/mailboxes

#mailing lists
subscribe talk@nblug.org
subscribe announce@nblug.org

# PGP/GPG settings
# If you don't have PGP set up, comment out these lines
set pgp_replyencrypt	# encrypt any replies to encrypted messages
set pgp_replysignencrypted	# automatically sign any messages 
                                # I encrypt
set pgp_show_unusable=no	# don't offer revoked keys in the 
                                # PGP key selection menu

# Folder hooks and other hook settings
source ~/.mutt/hooks

###################################
# Random and Weird Settings       #
###################################

# Editor Settings
# Use vim as the default editor with some special options for mutt
# such as spell check and 75 characters to a line
set editor="vim -c 'set nohlsearch noshowmatch modelines=0 tw=75 
 ↪et noai spell'"
# Show 7 lines of other email from a mailbox when reading 
# a specific email. Makes it easier to see where you are 
# in your mailbox when reading a message
set pager_index_lines=7		
# Keyboard Macros
macro index 	h "c?\t"	# show the "folder view" when 
                                # I hit 'h'

# extra weird settings
# this setting will highlight links and follow them 
# using w3m when I hit ctrl b
macro pager \cb \
<enter-command>'set pipe_decode'<enter>\
<pipe-entry>'w3m'<enter>\
<enter-command>'unset pipe_decode'<enter> \
'Follow links in w3m' 
auto_view text/html application/msword

#printer settings
set print_command="a2ps -g -Email -d -1 -M letter -R"

# abook settings
# abook is a cool command-line address book program 
# that works with mutt
set query_command="abook --mutt-query '%s'"
macro index \ca !abook\n
macro pager A |'abook --add-email'\n

As you can see, this muttrc file is quite involved. Besides the rather large list of options I defined, I also have included separate configuration files with the source option. For instance, I have separated out all my mutt color configuration into ~/.mutt/colors. Listing 2 shows a good sample ~/.mutt/colors file you can use to get started.

# color settings
color normal    white default
color attachment brightyellow default
color hdrdefault cyan default
color indicator brightwhite default
color markers   brightred default
color quoted    green default
color signature cyan default
color tilde     blue default
color tree      red default
color quoted1 green default

color index	brightyellow default ~N	# New
color index	yellow default ~O	# Old

#example of how to colorize based on FROM: 
#color index	magenta default '~f foo@example.com'

All of the color options follow the same syntax. First, the word color, then which object should be colorized and finally the foreground and background colors to use. I use default as my background color, so if I have a transparent window, the background is also transparent. You'll notice that the color options for the index (the mutt window that lists all of the messages in a mailbox) has an extra option at the end that lets you control what attributes it should match before it applies that color. For instance, in these two options:

color index	brightyellow default ~N	# New
color index	yellow default ~O	# Old

the ~N and ~O arguments match any new or old messages, respectively. You can use mutt's extensive matching language to match on all sorts of message attributes. In the above file, I provide a commented example for how to colorize a message based on its FROM: header.

As I mentioned earlier, I like to separate any settings that might differ between machines into a ~/.muttrc.local file. Here's an example of the settings you might want to keep there if you had all of your e-mail stored in a local Maildir folder:

# local mbox settings
set mbox_type=Maildir
set folder=~/Maildir
set spoolfile=+INBOX
set record=+sent-mail
save-hook . "+saved-messages-`date +%Y`"
mailboxes "=INBOX"

Here is an example .muttrc.local for a system that accesses mail remotely via IMAP:

set folder=imaps://mail.example.net/INBOX
set imap_user=username
set imap_pass=password
set spoolfile=+
set record=+.sent-mail
save-hook . "=.saved-messages-`date +%Y`"

Note here that I specify both the IMAP user name and IMAP password. If you want extra security, you will want to leave out the imap_pass option so your password is not in plain text. If no password is specified, mutt will prompt you when it connects to that IMAP server.

After you define your main mail folder settings, you also will want to define any other mailboxes you have besides INBOX. I keep these mailboxes defined in ~/.mutt/mailboxes, and I should note that the order does matter here. Whatever mailboxes you define in your configuration files will be checked by mutt for new mail. When you tell mutt to change to a different mailbox, it automatically will fill in the mailbox name with the next mailbox that has new mail. I use this feature a lot, especially at work, as it allows me to make sure I go through all of the high-priority mailboxes with new mail first. Here is a sample mailboxes file. Note that the = sign tells mutt that these folders are off the main folder:

mailboxes "=linuxjournal"
mailboxes "=consulting"
mailboxes "=nblug"
mailboxes "=saved-messages"
mailboxes "=sent-mail"

The final configuration file worth mentioning is ~/.mutt/hooks where I store all of my folder hooks and other settings. Hooks are a powerful feature in mutt that allow you to change your mutt settings on the fly based on your current folder, the recipient of an e-mail or contents in an e-mail when you reply to it. Hook syntax can get a bit complicated, so I recommend if you want to know more about a particular option, especially the index_format and folder_format syntax, that you reference the official documentation on mutt.org. Listing 3 shows a few example hooks I use to change how messages are sorted in some folders, tweak what signature to use on certain e-mail messages and even change my TO address when I reply to a message.

# The first options set defaults
unset sig_on_top
# default hook is 'set index_format="%4C %Z %{%b %d} 
# %-15.15L (%4l) %s"'
folder-hook . 'set index_format="%4C %Z %{%b %d} %-15.15L (%4l) %s"'
folder-hook . 'set sort=date'
folder-hook . 'my_hdr From: Kyle Rankin <foo@example.com>'
send-hook . unset signature

# Set special options when I'm in my nblug folder
folder-hook nblug 'set index_format="%4C %Z %{%b %d} 
 ↪%-15.15F (%4l) %s"'
folder-hook . 'set sort=date'
folder-hook nblug 'set sort=threads'
folder-hook nblug 'set signature="~/.mutt/.sig.nblug"

#default folder_format="%2C %t %N %F %sl %-8.8u %-8.8g %8s %d %f"
set folder_format="%2C %t %N %8s bytes - %d %f"

# these settings will pick a different signature file to use 
# depending on whether I'm sending email to nblug.org (one of my 
# mailing lists) or one of my consulting clients
send-hook '~t @nblug\.org$' 'set signature="~/.mutt/.sig.nblug"; 
 ↪my_hdr From: My Name <foo@example.com>'
send-hook '~t client@example\.com$' 
 ↪'set signature="~/.mutt/.sig.consulting"; my_hdr From: 
 ↪My Name <bar@example.com>'

# This is the actual hook I use to make sure emails to my 
# Linux Journal address have the proper FROM headers
reply-hook '~t lj@greenfly\.net' 'my_hdr 
 ↪From: Kyle Rankin <lj@greenfly.net>'

So there you have it. If your interest in mutt is piqued, these options should be more than enough to get you started. I also know that these settings won't appeal to everyone. That's the beauty of mutt—you can change the options until they do suit you. I still recommend once you get your base options configured that you spend a little time with the official documentation on mutt.org. There are many great examples and also many more options than I listed here that might solve a particular configuration problem you are having.