May 6, 2008

OfflineIMAP makes messages and attachments available locally

Author: Ben Martin

OfflineIMAP allows you to read your email while you are not connected to the Internet. This is great when you are traveling and really need an attachment from a message but cannot connect to the Internet.

You can use OfflineIMAP to sync all your email during the night so that it is all instantly available when you wake up. This is a security trade-off -- you gain speed and availability for your email at the expense of having to properly protect the local copy of all the email that is created on your laptop.

OfflineIMAP is designed to contact your IMAP servers and create a local copy of your email in maildir format. You then point your mail client at the local maildir tree and use your mail client as normal. OfflineIMAP can then sync any changes, such as which messages you have read and deleted, back to the server. OfflineIMAP performs a bidirectional sync, so new messages from the server are downloaded to your local maildir while any changes you have made locally are sent to the IMAP server.

If your email client does not support maildir format, you can use OfflineIMAP to sync email between two IMAP servers and ultimately accomplish the same thing. This scenario is a little more complex, as you need to install an IMAP server on your laptop, tell your email client to connect to the IMAP server on localhost, then use OfflineIMAP to keep the IMAP server on your laptop in sync with your main IMAP server. An alternative is to use OfflineIMAP to sync to a maildir repository as normal and tell your local IMAP server to use that maildir as its email source. This thread contains information on setting up courier-imap locally to serve up your mail.

OfflineIMAP packages are available for openSUSE, Ubuntu Gutsy, and from the Fedora 7 and 8 repositories. If no packages exist for your distribution, the documentation provides good information on installation from source. I used OfflineIMAP 5.99.2 from the Fedora 8 repository. Version 5.99.2 does not support the Gmail account type. Version offlineimap-5.99.7 from the Fedora rawhide repository does support Gmail but has another bug relating to directory creation which causes synchronization to fail. For these reasons I would recommend using the IMAP account type and manually configuring it for Gmail until package repositories contain later versions of OfflineIMAP.

The primary configuration file for OfflineIMAP is $HOME/.offlineimaprc, and you can find a commented template configuration file online. The configuration file defines one or more accounts. For each account you must set the local and remote repository. A repository is configured in its own section and contains the type for storing email locally, or IMAP to connect to a mail server. When connecting to an IMAP server you can specify the hostname, username, and password, and whether OfflineIMAP should use SSL to connect to the IMAP server.

Configuration and setup is shown below. First I create the configuration file using the sample that comes with the offlineimap package. The accounts directive is set to contain a single Gmail account. This account has both a local and remote repository so that OfflineIMAP knows where to store email locally and what server to contact. The local repository is a maildir in my home directory. The remote repository uses the type IMAP instead of Gmail because of the version issues discussed above. I have selected an appropriate email address as the remoteuser so spambots will make themselves known. The nametrans directive lets you change the name of folders in the local repository.
In this case I call re.sub twice to first change occurrences of INBOX, [Gmail], or [Google Mail] into root. One directory will be missed by this initial mapping, which is then accounted for by moving the Sent folder inside the root folder.
This translation is useful because Evolution expects your inbox to be directly in the root folder of your IMAP account. If you change where the local copy of INBOX is stored, Evolution can more naturally interact with the local mail repository.
You can also set up more elaborate folder name translations depending on your needs.

$ cp /.../offlineimap.conf ~/.offlineimaprc
$ vi ~/.offlineimaprc

accounts = my-gmail

[Account my-gmail]
localrepository = GMailLocalMaildirRepository
remoterepository = GMailServerRepository

[Repository GMailLocalMaildirRepository]
type = Maildir
localfolders = ~/.offlineimap-maildir-my-gmail
sep = .
restoreatime = no

[Repository GMailServerRepository]
type = IMAP
remoteuser =
remotehost =
ssl = yes
remotepassfile = ~/.offlineimap-pass-my-gmail
realdelete = no
nametrans = lambda foldername: re.sub('^Sent$', 'root/Sent', re.sub('^(\[G.*ail\]|INBOX)', 'root', foldername))


$ mkdir -p ~/.offlineimap-maildir-my-gmail

With this configuration in place, just run offlineimap. It will check its metadata and notice that you haven't performed any previous sync and download everything from your IMAP server.

You should then have a complete copy of your email in maildir format on your local machine. See the client notes for information on configuring your email client to directly use the email from this maildir. When you want to send your changes back to the main IMAP server and check for new email, just run offlineimap again. Alternatively, you can use the autorefresh directive in ~/.offlineimaprc to tell offlineimap to continue to sync your accounts every n minutes.

Normally, you should run OfflineIMAP without any command-line options to bidirectionally synchronize your configured email accounts, but OfflineIMAP accepts some options that might be handy for casual use. The -a option accepts a comma-separated list of accounts that you wish to synchronize. This can be great if you are expecting a message but have some accounts defined that are slower to sync than others. The -u option lets you choose one of many interfaces to OfflineIMAP. The default is the Curses.Blinkenlights interface, which you might find to be too distracting. TTY.TTYUI displays a simpler and less distracting progress report. You can also change the interface that will be used by default by altering the ui directive in ~/.offlineimaprc. The -c option allows you to specify an alternate location to ~/.offlineimaprc for the configuration file.

Having the contents of your IMAP account available offline means you don't have to seek out an Internet connection just to get an attachment or wonder if a particular message has been cached locally by your email client. If you are working with moderate-sized attachments, the ability to schedule your laptop to grab your email an hour before you wake up can save precious time when you are traveling.


  • Tools & Utilities
  • Mail & Messaging
  • Desktop Software
Click Here!