Taking back email – Part 2: OfflineIMAP

Recently, I decided to revamp my email setup. I don’t much like email, but it’s such an important method of communication that I needed to get it under control. I’m putting together a several-post guide explaining my reasoning, technical details, and my new email process.

Other posts in this series (all will be linked here as the posts go up:)


OfflineIMAP is a simple Linux command-line tool that syncs email messages and folders from an IMAP server to your computer (and back). I use it to aggregate emails from my three accounts into a directory on my home server. I have it set up to fetch my email once an hour during my awake-time of the day.

I have OfflineIMAP installed on my home server. My mail is collected and indexed on my server, then I have the folders synced to my home and work computers with Syncthing.

Installing OfflineIMAP

OfflineIMAP is likely packaged for your Linux distro of choice. In Arch Linux:

sudo pacman -S offlineimap

After installing, you should copy the default configuration into your user directory and edit it:

cp /usr/share/offlineimap/offlineimap.conf ~/.offlineimaprc
vim ~/.offlineimaprc

The default configuration file is VERY heavily commented and is pretty clear. I’m just going to hit some highlights here.



accounts = ajy,gmail,work

Start with a comma-separated list of accounts. Remember those account names because you’ll be needing them shortly. In fact, I like keeping my account names consistent from OfflineIMAP to notmuch to alot and msmtp, through the whole process.


So far I am doing nothing with this section.


[Account ajy]
localrepository = ajyLocal
remoterepository = ajyRemote
maxage = 730

I’m initally only syncing the last two years (730 days) of mail. I don’t need to go further back. Note that I used the account name from above (ajy), and I’m specifying two repositories that I’m going to define next:

[Repository ajyLocal]
type = Maildir
localfolders = ~/mail/ajy
sep = /

[Repository ajyRemote]
type = IMAP
remotehost = imap.example.com
remoteuser = aaron@example.com
## do something for password ##
folderfilter = lambda foldername: foldername not in [
        'Trash', 'Spam', 'Templates', 'Queue', 'Drafts']

In the local repository, everything is pretty straightforward. Using / as a separator means that your email messages will be organized in hierarchical folders to match your IMAP structure. If you’re using Gmail, use type = GmailMaildir.

The remote repository has a bit more going on:

  • For normal accounts, type = IMAP is appropriate. For Gmail, use: type = Gmail as this contains a bit of auto-configuration that will be handy for you.
  • You have some options for how to handle your password. I’m not going to get into that here, but read the config file documentation.
  • The folderfilter setting above excludes certain folders from being synced.

To find the cert_fingerprint setting for your server, run this command:

openssl s_client -connect imap.example.com:993 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -in /dev/stdin

Of course, replace imap.example.com with your remotehost name. You’ll probably get the fingerprint with colons: XX:XX:.... Remove the colons for the purpose of this config file.

More accounts?

Add a new [Account ...] section and configure two repositories for each account as above.


Run offlineimap > offlineimaplog.txt to do an initial sync and see if it all works. Hopefully you should get a meaningful error if something goes wrong. You’ll see it in the offlineimaplog.txt file that’s created in the above command.

Running with cron

Right on, it’s all working great. Add this to your crontab:

47 5-21 * * * offlineimap && notmuch new

I haven’t gotten to notmuch in this tutorial yet, but the && notmuch new part just refreshes the tag and index database after offlineimap is done.

This will run offlineimap on the 47th minute of the hour, from 5:47 AM till 9:47 PM, each day.

A note about syncing

I’ve mentioned that since I have multiple computers that I spend a lot of time on (home and work) I want to have my email in the same state from machine to machine. When I get into how to use notmuch, you’ll see that I’m making changes to my email messages that are not going to be synced back to the IMAP server, so I need to use my home server (or an online VPS) to act as the central server.

To accomplish this, I use Syncthing to sync my mail folder (and thus, the notmuch database) to both my workstations. The only drawback is that syncing, though fast, is not immediate – so if I know there has been a change in the last 30 seconds or so (like, the cron above has just run), I’ll wait a minute or so to refresh my mailbox.

Up Next: configuring notmuch to work with OfflineIMAP

Leave a Reply