The Mutt Email Program

Table of Contents

last revision
19 April 2015, 3:15pm
book quality
just started

Mutt is a rather nice 'curses' bases email client. That is to say that it runs in a terminal. It seems better than 'alpine' or 'elm' and has a 'vi' like feel to it. Mutt can be used with the abook contact management software and with the offlineimap download tool.

Help ‹↑›

view the mutt manual (not the 'man' page)

 zless /usr/share/doc/mutt/manual.txt.gz
 vim /usr/share/doc/mutt/manual.txt.gz a very good help guide to mutt some good mutt tips

Contacts And Addresses ‹↑›

Email Aliases ‹↑›

An email alias is a word that can be used instead of the full email address of a person. Aliases can also be generated from an external file

create an email alias in the .muttrc file

 alias muttdude (Michael Elkins)

create an email alias with a long name

 alias me M J Bishop

create an email alias 'work' with a long name 'office people'

 alias work office people,,

create an email that refers to previous aliases

 alias theguys manny, moe, jack

add an email alias based on the sender (added by default to ~/.muttrc)


in the '.muttrc', define a file to contain all email aliases

 set alias_file=~/.mutt/aliases
 source ~/.mutt/aliases

It is ok just to keep all your email aliases in the .muttrc file rather than defining a separate file to contain them. Its a matter of personal preference.

Address Books ‹↑›

query an external program for email addresses


a configuration for using 'Q' queries with 'abook'

set query_command = "abook --mutt-query '%s'" macro generic,index,pager \ca "<shell-escape>abook<return>" "launch abook" macro index,pager A "<pipe-message>abook --add-email<return>" "add the sender address to abook" ,,,

Abook And Mutt ‹↑›

The 'abook' application can be used to manage contact details including email address. abook is designed to be used with mutt and can convert contact information from and to a variety of formats (eg csv, vcard ...)

convert a set of mutt aliases into abook contact information format

 abook --convert --informat mutt --infile ~/.mutt/aliases --outformat abook --outfile ~/.abook/addressbook

Navigating ‹↑›

external tools
rolo - an address book using vcard
abook - plain text
lbdb - queries lots of things
- *, go to the last message - =, go to the first message

Sorting Messages ‹↑›

order the index of messages by the date received


configure mutt to always sort received messages by the date sent

 set sort=date-sent

configure mutt to sort received message by subject (into threads)

 set sort=date-sent

set sorting by threads in the work folder

 folder-hook work set sort=threads
 folder-hook . set sort=date-sent

It is necessary to set a default sorting criterion for the '.' folder so that when the 'work' folder is exited the sorting criterion returns to normal

Reading Mail ‹↑›

Paging Mail ‹↑›

dont go to the next email automatically when paging through mail

 use "pager_stop" ...

Attachments ‹↑›

select message with attachment.. press enter to view in default app. or s to save attachment

Sending Mail ‹↑›

navigating keystrokes

Receiving Mail ‹↑›

This tells Mutt to beep when you receive a new message while your mailbox is open.

 set beep_new
 unset beep_new
This tells Mutt not to beep when you receive a new message while your mailbox is open.

Deleting Mail ‹↑›

sending mail commands
R - recall a draft message

delete mail without asking (put in ~/.muttrc)

 set delete

a macro to move a message to trash in Gmail

  macro index D \
    "<save-message>+[Gmail]/Trash<enter>" \
    "move message to the trash"

Caching Mail ‹↑›

In this case, 'caching' refers to storing a copy of emails locally on the computer where you are working, as opposed to on the server. This is useful for speed and for maintaining an archive of your mails.

make a cache for mail headers and bodies

   in bash: mkdir ~/.mutt; mkdir ~/.mutt/cache/
   in .muttrc:
    set header_cache =~/.mutt/cache/headers
    set message_cachedir =~/.mutt/cache/bodies

Editing Email Messages ‹↑›

Any text editor can be used to edit email messages with mutt

configure mutt to use the 'vim' editor to edit messages

 set editor="vim"  put this in the '.muttrc' configuration file

use vim to edit messages and start vim in 'insert' mode

 set editor="vim -c start"

start vim in edit mode at last line with Z and X exiting and saving

 set editor="vim + -c 'nmap X :wq<cr>' -c 'nmap Z :wq<cr>' -c start"

Searching ‹↑›

search for the next message with 'bob' in the header (subject etc)


search for the next message with 'machine' in the message

 / ~b machine
 <esc>b machine    the same

Attachments ‹↑›

a macro to attach a particular file to an email message

 macro compose b "<attach-file><kill-line>~/fragment.c<enter>"

bind 'b' to enter a folder and then let user complete

 macro compose b "<attach-file><kill-line>~/Pictures"

Multiple Attachments ‹↑›

Mutt doesnt have any one command to attach multiple files to an email, and the macro system is not sofisticated enough to solve this problem with a macro, but nevertheless a usefull macro can be written.

attach multiple files in same folder from the file browser

 use 't' to tag them, then ';'-Enter.

The recipe may not work if their are less than 4 files with 'new' in their name, since 't' will toggle the tag and therefore untag the last file, and so not attach it.

try to tag 4 files which have 'new' in their names and attach

 macro compose b "<attach-file><kill-line>~/Pictures<tab><tab>\

Menus Or Screens ‹↑›

In mutt the application interface is divided into menus or 'screens'. Each screen has its own set of keybindings and macros. To see the name of the current screen press ? and look at the bottom of the display.

valid screens generic, alias, attach browser, editor, index, compose, pager, pgp, postpone and mix.

Macros ‹↑›

A macro is a way of coding new functionality into mutt (without writing c code or attaching functions to key strokes. Macros a fairly simple, they dont have any associated programming language.

The last parameter of the macro is a 'help string' which will be displayed when the user presses '?' in the relevant menu (screen).

macro which binds 'b' to run a bash command (ls)

 macro index b "<shell-escape>ls -thor<enter>" "list folder"

a macro to do something with mailcap

 macro attach x ":set mailcap_path=~/.mutt/xanthe-open-mailcap\n<view-mailcap>:reset mailcap_path\n"

a macro which applies to 2 screens (contexts) index & pager

 macro index,pager y <change-folder>?<toggle-mailboxes>

enter some text and then go to beginning of line

 macro compose b "<attach-file><kill-line>~/Pictures &^A"

use 2 tabs to open the file browser from the editor

 macro compose b "<attach-file><kill-line>~/Pictures/<tab><tab>"

print something and then delete one character

 macro compose b "<attach-file><kill-line>~/Pictures/<backspace>"

a macro to edit and reload the .muttrc file in all contexts

 macro generic 0 "!vim ~/.muttrc\n:source ~/.muttrc\n" "edit & reload ~/.muttrc"

Tips For Macros ‹↑›

<shell-escape> is equivalent to "!" <enter-command> is the same as ":" <enter> is the same as "\n" etc

Configuration And Customising Of Mutt ‹↑› A good page about customising mutt keybindings etc.

Mutt uses the usual unix style configuration of a plain text file at ~/.muttrc or ~/.mutt/muttrc or maybe elsewhere

reload the mutt configuration file in a running mutt session

 :source ~/.muttrc

a macro to reload the .muttrc file

 macro index <F12> "<enter-command>source ~/.muttrc<enter>" "Reload ~/.muttrc"

a macro to edit and reload the .muttrc file in all contexts

 macro generic 0 "!vim ~/.muttrc\n:source ~/.muttrc\n" "edit & reload ~/.muttrc"

create a 'header cache' to speed up the mutt startup process

 mkdir ~/.mutt; mkdir ~/.mutt/hcache   in bash
 set header_cache=~/.mutt/hcache/fastmail  in the .muttrc file

automatically cancel a message if you leave the subject line blank

 set abort_nosubject=yes  ok values: yes, ask-yes, ask-no, no

ask you for blind carbon copy recipients when you create a mail or reply

 set askbcc

disable the 'press any key to continue...' message

 unset wait_key

Using Maildir ‹↑›

The 'maildir' email system involves mail being spooled into a local folder with each message contained in a separate file.

The configurations below are untested!! ...

a configuration for using a maildir with mutt --------- in bash: mkdir ~/Mail/gmail in the .muttrc file: source ~/Mail/gmail/ set mbox_type=Maildir set folder=$HOME/Mail spoolfile=+Personal/INBOX ,,,

The configuration below requires an imap fetcher and synchroniser such as 'offlineimap' to actually deliver the mail to the local folder.

a maildir setup with Gmail for mutt

    set mbox_type   = Maildir
    set sendmail    = /usr/bin/msmtp

    set folder      = ~/Mail
    set spoolfile   = "+INBOX"
    set mbox        = "+[Gmail]/All Mail"
    set postponed   = "+[Gmail]/Drafts"
    unset record

    mailboxes +INBOX

a configuration for using a multiple accounts --------- in bash: mkdir ~/Mail/gmail/ in the .muttrc file: source ~/path-to-mbnames-muttrc-mailboxes folder-hook Personal set from="" folder-hook Work set from="" set mbox_type=Maildir set folder=$HOME/Mail spoolfile=+Personal/INBOX ,,,

Offlineimap And Mutt ‹↑›

Offline imap allows one to work on email completely 'offline', that is without an Internet connection. The 'offlineimap' program creates a local copy of all imap mail and then synchronises both ways when an internet connection is established with the imap mail server. This is a good idea, probably better than using mutts imap support directly

get started with offline imap

    sudo apt-get install offlineimap
    cp /usr/share/doc/offlineimap/examples/offlineimap.conf.minimal \
    vim ~/.offlineimaprc
    # and edit the local folder and imap settings as desired

It is better to use subfolder of the ~/Mail folder to allow for multiple accounts on the one computer.

set up a local folder for downloaded email

 mkdir ~/Mail/Gmail

sync offline imap every 3 minutes

 sudo crontab -e
 */3 * * * * /path/to/

an example configuration for a fastmail email account

   accounts = Fastmail 

   [Account Fastmail]
   localrepository = Local
   remoterepository = Remote

   [Repository Local]
   type = Maildir
   localfolders = ~/Mail/Fastmail

   [Repository Remote]
   type = IMAP
   remotehost =
   remoteport = 993
   remoteuser = 
   ssl = yes
   #cert_fingerprint = fa86c1ca2d4f805e8fe7b8e7076a3ad2ccc52bb4
   holdconnectionopen = yes
   remotepass = somepassword

It may be wiser to not use the 'remotepass' key and just enter the password when prompted. a good article about mutt + gmail + offlineimap

an example offlineimap configuration for a gmail account

[general] ui = ttyui accounts = Gmail

[Account Gmail] localrepository = Gmail-Local remoterepository = Gmail-Remote

[Repository Gmail-Local] type = Maildir localfolders = ~/Mail/Gmail

[Repository Gmail-Remote] type = Gmail remoteuser = remotepass = secret realdelete = no maxconnections = 3 sslcacertfile = /etc/ssl/certs/ca-certificates.crt


Multiple Accounts With Offlineimap ‹↑›

a configuration for multiple email accounts

    ui = ttyui
    accounts = Personal,Work

    [Account Personal]
    localrepository = Personal-Local
    remoterepository = Personal-Remote

    [Account Work]
    localrepository = Work-Local
    remoterepository = Work-Remote

    [Repository Personal-Local]
    type = Maildir
    localfolders = ~/Mail/Personal

    [Repository Work-Local]
    type = Maildir
    localfolders = ~/Mail/Work

    [Repository Personal-Remote]
    type = Gmail
    remoteuser =
    remotepass = secret
    realdelete = no
    sslcacertfile = /etc/ssl/certs/ca-certificates.crt

    [Repository Work-Remote]
    type = Gmail
    remoteuser =
    remotepass = secret
    realdelete = no
    sslcacertfile = /etc/ssl/certs/ca-certificates.crt

Isync And Mutt ‹↑›

isync is an alternative to the offlineimap program.

Gmail And Mutt ‹↑›

The listing below has an example configuration for using mutt with a gmail account. It also has good tips for customizing mutt in general

The 'sidebar' functions only seem to be available in a special version of mutt.

install a mutt version which has a sidebar

 sudo apt-get install mutt-patched

a gmail config

#account settings set from="YOUR_GMAIL_ADDRESS" set realname = "REAL_NAME" set imap_user = "YOUR_GMAIL_ADDRESS" set imap_pass = "PASSWORD" set smtp_url = "smtp://" set smtp_pass = "GMAIL_PASSWORD"

set folder = "imaps://" set spoolfile = "+INBOX" set postponed = "+[Gmail]/Drafts" set trash = "imaps://[Gmail]/Trash" set record = "+[Gmail]/Sent Mail" set header_cache =~/.mutt/cache/headers set message_cachedir =~/.mutt/cache/bodies set certificate_file =~/.mutt/certificates

set move = no #Stop asking to "move read messages to mbox"! set imap_keepalive = 900

# Header related stuff ignore "Authentication-Results:" ignore "DomainKey-Signature:" ignore "DKIM-Signature:" hdr_order Date From To Cc

ignore * unignore from: date subject to cc unignore x-mailing-list: posted-to: unignore x-mailer:

# Sorting, Markers etc. set markers=no # don't put '+' at the beginning of wrapped lines set pager_index_lines= 10 # how large is the index window? set sort = 'threads' set sort_aux = 'last-date-received'

# Set which Editor to use for composing Emails. set editor= '/usr/bin/emacs'

# set up the sidebar set sidebar_width=24 set sidebar_visible=yes set sidebar_delim='|' set sidebar_sort=no

# which mailboxes to list in the sidebar, # you can add your Labels in Gmail to the Sidebar. mailboxes =All Mail =INBOX =Drafts =Sent Mail =Trash

# color of folders with new mail color sidebar_new yellow default

#Sidebar Navigation bind index CP sidebar-prev bind index CN sidebar-next bind index CO sidebar-open bind pager CP sidebar-prev bind pager CN sidebar-next bind pager CO sidebar-open

# b toggles sidebar visibility macro index b 'toggle sidebar_visible' macro pager b 'toggle sidebar_visible'

# Remap bounce-message function to "B" bind index B bounce-message

#make mutt colorful! color attachment brightmagenta default color error brightred default color hdrdefault red default color indicator brightyellow red color markers brightcyan default color message brightcyan default color normal default default color quoted brightblue default color search default green color signature red default color status yellow blue color tilde magenta default color tree magenta default ,,,

Keybindings ‹↑›

make the <esc> key go to the first message in the email index screen

 bind index <esc> first-entry

a list of functions that can be bound to keys

bind 'b' to go to previous page (just like 'less') -------- bind pager b previous-page ,,,

Colors ‹↑›

change the colors of mutt

 color object foreground background [ regexp ]

color mail with high importance in the header red

 color header red default “^Importance: high”

color unread mail bright yellow

 color index color227 default “~U”

color deleted mail in the index screen grey

 color index color239 default “~D”

color the mail header

 color hdrdefault color241 default

color the status as 30

 color status color30 default

colour quoted text in an email '60'

 color quoted color60 default

within mutt colour quoted text (the 'replied to' text) green

 :color quoted green default

These color changes made within mutt only take effect when you reenter the email message.

deleting keystrokes
$ really delete messages marked for deletion
d mark a message for deletion
D delete all messages matching a pattern

Bash And Mutt ‹↑›

The bash shell can be used for fun and profit to maintain and configure a mutt installation

a couple of aliases to make config tasks easier ---------- alias muttrc='vim ~/.muttrc' alias muttdoc='vim /usr/share/doc/mutt/manual.txt.gz' ,,,

show a listing of the current folder within mutt


macro which binds 'b' to run a bash command (ls)

 macro index b "<shell-escape>ls -thor | less<enter>"

Vim And Mutt ‹↑›

The venerable vi-improved text editor can be used with the mutt email client program. For example to edit emails. Macros can be set up within vim to make the editing of mail easier.

Organising Mail ‹↑›

Spam ‹↑›

a macro to move a message to the spam folder in gmail

    macro index S \
      "<save-message>+[Gmail]/Spam<enter>" \
          "mark message as spam"

Tagging Mail ‹↑›

In order to manipulate multiple emails at once within mutt one first 'tags' the target emails and then applies the desired function

Tag all mail messages with have the word 'books' in the headers

 T books

Tag all mail messages with have the word 'books' message text

 T ~b  books

Fastmail Config ‹↑›

set set set imap_pass=<password> set folder="imaps://" set record="imaps:// Items" set postponed=imaps://

# for sending mail set smtp_url="smtps://$my_user:<password>" set header_cache=~/.mutt/hcache/fastmail set from=""

# use vim to edit messages set editor="vim" set spoolfile="=" set mask="."

alias david McBain alias hamish alias sonia

Offlineimap ‹↑›

offlineimap is a program which allows mutt to work with a Maildir. It is also useful for making backups of an imap account


valid 'objects' to use with the 'color' command
body -match regexp in the body of messages)
bold -(hilighting bold patterns in the body of messages)
error -(error messages printed by Mutt)
header -(match regexp in the message header)
hdrdefault (default color of the message header in the pager)
index (match pattern in the message index)
indicator (arrow or bar used to indicate the current item in a menu)
markers (the ``+'' markers at the beginning of wrapped lines in the pager)
message (informational messages)
quoted (text matching $quote_regexp in the body of a message)
quoted1 quoted2, ..., quotedN (higher levels of quoting)
search (hiliting of words in the pager)
status (mode lines used to display info about the mailbox or message)
tilde (the ``~'' used to pad blank lines in the pager)
tree (thread tree drawn in the message index and attachment menu)
underline (hiliting underlined patterns in the body of messages)