If you’re interested in using Mutt as a mail client on OS X, you might like to cache your mail offline so that you can index it. Once you’ve indexed it, searching and manipulating it is straightforward and very fast.

In this post, I explain how to set up Mutt on OS X with offlineimap (an IMAP synchroniser) and notmuch (a search programme).

I assume you already have Homebrew already installed, and no fear of the command line (Mutt is all in the terminal).


You can download and install Mutt using the standard brew install command

brew install mutt

However, this is just the standard installation, with no bells and whistles. Many patches exist for mutt, which add features. The sidebar, trash, and confirm attachment are 3 very popular ones. In this case, the command becomes

brew install kevwil/patches/mutt --with-trash-patch --with-sidebar-patch --with-confirm-attachment-patch --with-debug

The more patches you try to apply, the likelier you are to have a conflict (trying to change source code that’s already changed), so it’s worth picking the most important ones to you. If you’d like to install another patch and keep using brew install, you can use

brew edit kevwil/patches/mutt

Then, in the code that appears, add another line underneath

option "with-my-patch", "Apply my custom patch"

as well as

  patch do
    url "http://domain.com/path-to-patch-in-question"
    sha1 "sha1-of-file"
  end if build.with? "my-patch"

Replacing the URL and sha1-of-file with the URL of the patch and the sha1 of the patch file, respectively. Then add your option --with-my-patch:

brew install kevwil/patches/mutt --with-trash-patch --with-sidebar-patch --with-confirm-attachment-patch --with-my-patch

Additional Programmes (Simple)

Next up is to install offlineimap, MSMTP and some command line tools for search (including some Perl modules). It’s just a collection of simple one-liners (although the order is important):

brew install offlineimap
brew install msmtp
brew install notmuch
brew install readline
brew install urlview
brew install w3m
brew install openssl
sudo cpan install Mail::Box::Maildir
sudo cpan install String::ShellQuote
brew link --force readline
cpan Term::ReadLine::Gnu
brew unlink readline


Mutt in particular is extremely configurable, but the main lines you’ll need in ~/.muttrc are:

set mbox_type   = Maildir
set sendmail    = "/usr/local/bin/msmtp --read-envelope-from"

set folder = ~/imap_mail
set spoolfile = "+INBOX"

In ~/.msmtp:

account default
host <SMTP HOST>
port <SMTP PORT>
protocol smtp
auth on
password <SMTP PASSWORD>
tls on
tls_trust_file /usr/local/etc/openssl/cert.pem
logfile ~/.msmtp.log

In ~/.offlineimaprc

accounts = joelbuckley

[Account joelbuckley]
localrepository = Local
remoterepository = Remote
status_backend = sqlite
postsynchook = notmuch new

[Repository Local]
type = Maildir
localfolders = ~/imap_mail

[Repository Remote]
#readonly = true
sslcacertfile = /usr/local/etc/openssl/cert.pem
type = IMAP
remotehost = <HOST>
remoteuser = <USERNAME>
remotepass = <PASSWORD>
folderfilter = lambda folder: folder not in ['Contacts', 'Calendar', 'Tasks', 'Notes'] # Necessary for exchange hosts

Be sure to replace all of the instances of with whatever is necessary in your situation. Then, run

notmuch setup


launchctl load ~/Library/LaunchAgents/homebrew.mxcl.offlineimap.plist

Your mutt installation should now be checking your email regularly, with frequency defined in ~/Library/LaunchAgents/homebrew.mxcl.offlineimap.plist; if you’d like to alter this, change the value underneath <key>StartInterval</key>``

Configuring search

Download mutt-notmuch.pl and place it somewhere convenient for your (I put mine in ~/bin/). Enable it as a script (chmod +x ~/bin/mutt-notmuch.pl), and test that it works by running

$ ~/bin/mutt-notmuch.pl

You should receive usage advice. If you receive an error, make sure you have installed the necessary packages listed above, as well as performed the link-readline-unlink steps in the correct order.

Then, add the following lines to your ~/.muttrc:

macro index,pager <F8> \
        "<enter-command>unset wait_key<enter><shell-escape>~/bin/mutt-notmuch.pl --prompt search<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter>" \
        "search mail (using notmuch)"
macro index,pager <F9> \
        "<enter-command>unset wait_key<enter><pipe-message>~/bin/mutt-notmuch.pl -o ~/.cache/notmuch/mutt/thread thread<enter><change-folder-readonly>~/.cache/notmuch/mutt/thread<enter><enter-command>set wait_key<enter>"

This binds F8 to search (so you can find emails from specific people within specific date ranges, for example), and F9 to thread search (so that you can search for all related emails in a thread). F9 works well with search results, too.

I hope this has helped you configure Mutt on OS X. Please leave a comment if you have any questions, I’ll do my best to help.