Jason's Blog

A stochastic thought repository

Quick and Simple Email Management With Mutt, Offlineimap, Imapfilter, Msmtp, and Archivemail

| Comments

After using Gmail for many years, about a year ago my academic advisor introduced me to mutt. I’ve been using it as my mail reader ever since, in combination with offlineimap, imapfilter, msmtp, and most recently archivemail. The setup is highly customizable, incredibly fast, and since the configuration is completely in text files, I can quickly make and keep track of changes across my multiple computers with git.

The downside of this approach is it requires a bit of time and possibly troubleshooting up-front to configure. But as always, Google is your friend. Several other good tutorials exist explaining how to use and configure these tools in various combinations, and I wanted to add examples from my own configuration to the mix in the hope that others find them useful.

Some would also point out that mutt really could technically do most of this by itself. This absolutely works, but I like to have a division of labor of sorts, splitting up the fetching, sorting, sending, and reading between different programs. After all, it is the Unix Philosophy.

This is the Unix philosophy: Write programs that do one thing and do it
well. Write programs to work together.

Doug McIlroy

My example setup will include two inboxes: one for school, and one for Gmail. I have a few more mailboxes than this setup, but it’s easy to extend from this as per your own needs.


It’s easiest to keep everything together under one directory for git to keep track of. From there, we can use symlinks or specify directly within the various commands about where the configuration files are.

I’ve created an example repository on Github for those that want to follow along with a similar file structure. Note that to go from example to working copy will require a bit of editing.

Syncing mail with Offlineimap

Offlineimap uses the IMAP protocol to synchronize a local copy of all your email messages for multiple accounts in a maildir format. Having your email be local means that reading is fast, since the email has already been downloaded to your machine. Any changes you make such as deleting, changing flags (important, read, unread,…), or moving the email to a different folder are performed on the local copy, which is periodically synchronized with the remote copy.

A fully annotated configuration file is available if you want to see all the bells and whistles available. Alternately, check out the minimal configuration needed to get working. My example configuration is here.

I suggest that you test it from the terminal to make sure that it’s working at this point. You will need to disable the hook to imapfilter if you haven’t configured it yet. Other sources of errors may be the port number, or if you’re trying to connect to Gmail, be sure you have enabled IMAP in the Gmail interface.

offlineimap -c ~/.mail_configs/offlineimaprc

Sorting mail with Imapfilter

Imapfilter is another program which is able to sort and move messages around on the IMAP server. I use it before calling offlineimap to sort my mail into the correct folder (ie, messages for a certain class into a given folder). The configuration file can use regular expressions to do the sorting, and is extendable using Lua, if you want to do so.

Sorting can take place based on who an email is sent from, sent to, title contents, body contents, other header information, email size, age of the email, email status (recent, unread,…) and many other possibilities in combination.

My example configuration is actually quite simple. You should really look at the configuration manual and especially another example to see other things you can do with it.

You can test your configuration using the following command.

imapfilter -vc ~/.mail_configs/imapfilter/file_name.lua

Reading mail with Mutt

Now that you hopefully have your email synchronized to your machine, it’s time to set up mutt to read it. This is the most configuration intensive portion of this how-to, but fortunately we can split up mutt’s configuration file in a sensible and modular way for simplicity.

Before I throw down my own configuration files, I will point you to a page with a list of several different mutt configuration examples. They have varying levels of documentation in them, and try to do different things. This is, again, because mutt is so darn configurable that it really can do just about anything you want to do. As I mentioned previously, most of these setups let mutt handle everything regarding connecting to IMAP servers, sorting, connecting to SMTP servers to send and some other things. It’s a good place to look for ideas.

Moving on to my own configuration: the configuration files are split up as follows:

  • muttrc: This is the main configuration file. All the other configuration files are included from this file.
  • common: Some global settings that I want to apply to every email account I read.
  • colors: What the colors you want to be used in the display are. It uses the same Zenburn color scheme as this blog appears in.
  • macros: A set of a few keybindings that I find useful.
  • mailcap: This file tells mutt how to open attachments automatically. Your distribution may come with it’s own mailcap file. If so, I recommend that you remove the set mailcap_path statement in the common file and use it (unless you want to override it as I have).
  • pgp: If you do use use pgp or gpg encryption or signing email (or want to do so, all the cool kids are doing it :P), then this is the configuration file for doing that. If you have no idea or interest in this, then ignore this file and remove the corresponding source statement from the muttrc file.
  • school and gmail: These are configuration files that are specific to the these specific email accounts, such as account specific signatures and such. See the folder hooks in muttrc used to load these based on what folder mutt is looking at. Also, notice that these are very simple configuration files. It is trivial to add more if you have more email accounts.

Sending mail with Msmtp

Msmtp is a very simple SMTP client. It contacts the SMTP server with your account credentials when you send mail, and then passes the sent email to the server.

To use it, first set up your configuration file. My example configuration file is here, but you can also look at another simple example.

Once you have your file set up, you can test it from the terminal to make sure it’s working. Assuming that it is working, you should see information about the SMTP server and the encryption certificate flash by, otherwise, there is an error. In particular, if a self-signed certificate is being used, or a certificate from an uncommon signing authority, you may need to ignore the certificate check as shown in my configuration file. Also, check to see what ports are being used by the server in question.

# Replace ACCOUNT_NAME with your account.
# In my example, this would be either 'school' or 'gmail'.
msmtp -C ~/.mail_configs/msmtp -Sa ACCOUNT_NAME

Saving old emails with Archivemail

Here is an example that will take all mail from before January 1st, 2011 within the directory or file cpts111, and put it into a gzipped mbox file cpts111_records_fall_2010.gz.

archivemail -D 2011-1-1 -uv --archive-name cpts111_records_fall_2010 cpts111

I can also iterate over all the directories correspoding to each class that I have set up. A separate archive for each directory will be created. My inboxes relating to classes are labeled starting with their with either ‘ee’ or ‘cpts’.

ls | egrep "^(cpts|ee)" | xargs archivemail -D 2011-1-1 -uvs _records_fall2010

It is also possible to set up archivemail to run from a cron job and keep a running archive, keeping your inbox clean of files older than a certain number of days, but as I don’t use this personally, I leave the explanation to others. Check out the man page for archive mail or Google to read many good examples online.

Encrypting your Passwords with Gnome-Keyring

I’ve written another post with links pointing to keeping your passwords encrypted with Gnome-Keyring rather than having them be in plain text in your configuration files. For a single person computer, the above portion works just fine, but encryption never hurts.

To summarize, here are the links from the other post to integrate msmtp with gnome-keyring and offlineimap with gnome-keyring. Imapfilter integration is explained in my own post.

Take a look at the files in the lib directory of my example configuration for the helper files, and how they are used in each of the configuration files.


  • May 30, 2012: Updated post and created an example mail configuration on Github.
  • Jul. 30, 2011: Fixed typo in mutt configs. Postpone -> Postponed
  • Jan 16, 2011: Added encrypting passwords with Gnome-Keyring
  • Jan 10, 2011: Initial post.