Method of Operation

OfflineIMAP traditionally operates by maintaining a hierarchy of mail folders in Maildir format locally. Your own mail reader will read mail from this tree, and need never know that the mail comes from IMAP. OfflineIMAP will detect changes to the mail folders on your IMAP server and your own computer and bi-directionally synchronize them, copying, marking, and deleting messages as necessary.

With OfflineIMAP 4.0, a powerful new ability has been introduced -- the program can now synchronize two IMAP servers with each other, with no need to have a Maildir layer in-between. Many people use this if they use a mail reader on their local machine that does not support Maildirs. People may install an IMAP server on their local machine, and point both OfflineIMAP and their mail reader of choice at it. This is often preferable to the mail reader's own IMAP support since OfflineIMAP supports many features (offline reading, for one) that most IMAP-aware readers don't. However, this feature is not as time-tested as traditional syncing, so my advice is to stick with normal methods of operation for the time being.

Prerequisites

In order to use OfflineIMAP, you need to have these conditions satisfied:

• Your mail server must support IMAP. Most Internet Service Providers and corporate networks do, and most operating systems have an IMAP implementation readily available.

• You must have Python version 2.2.1 or above installed. If you are running on Debian GNU/Linux, this requirement will automatically be taken care of for you. If you do not have Python already, check with your system administrator or operating system vendor; or, download it from the Python website. If you intend to use the Tk interface, you must have Tkinter (python-tk) installed. If you intend to use the SSL interface, your Python must have been built with SSL support.

• Have a mail reader that supports the Maildir mailbox format. Most modern mail readers have this support built-in, so you can choose from a wide variety of mail servers. This format is also known as the "qmail" format, so any mail reader compatible with it will work with OfflineIMAP. If you do not have a mail reader that supports Maildir, you can often install a local IMAP server and point both OfflineIMAP and your mail reader at it.

System-Wide Installation, Debian

If you are tracking Debian unstable, you may install OfflineIMAP by simply running the following command as root:

apt-get install offlineimap

If you are not tracking Debian unstable, download the Debian .deb package from the OfflineIMAP website and then run dpkg -i to install the downloaded package. Then, skip to Configuration below. You will type offlineimap to invoke the program.

System-Wide Installation, Other

Download the tar.gz version of the package from the website. Then run these commands, making sure that you are the "root" user first:

tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z
python2.2 setup.py install

On some systems, you will need to use python instead of python2.2. Next, proceed to Configuration below. You will type offlineimap to invoke the program.

Single-Account Installation

Download the tar.gz version of the package from the website. Then run these commands:

tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z

When you want to run OfflineIMAP, you will issue the cd command as above and then type ./offlineimap.py; there is no installation step necessary.

Tk.Blinkenlights

Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and informative of the overall picture of what OfflineIMAP is doing. I consider it to be the best general-purpose interface in OfflineIMAP.

Tk.Blinkenlights contains, by default, a small window with a row of LEDs, a small log, and a row of command buttons. The total size of the window is very small, so it uses little desktop space, yet it is quite functional. The optional, toggleable, log shows more detail about what is happening and is color-coded to match the color of the lights.

Tk.Blinkenlights is the only user interface that has configurable parameters; see the example offlineimap.conf for more details.

Each light in the Blinkenlights interface represents a thread of execution -- that is, a particular task that OfflineIMAP is performing right now. The colors indicate what task the particular thread is performing, and are as follows:

The name of this interfaces derives from a bit of computer history. Eric Raymond's [Jargon File] defines blinkenlights, in part, as:

Front-panel diagnostic lights on a computer, esp. a dinosaur. Now that dinosaurs are rare, this term usually refers to status lights on a modem, network hub, or the like.

This term derives from the last word of the famous blackletter-Gothic sign in mangled pseudo-German that once graced about half the computer rooms in the English-speaking world. One version ran in its entirety as follows:

ACHTUNG! ALLES LOOKENSPEEPERS!

Das computermachine ist nicht fuer gefingerpoken und mittengrabben. Ist easy schnappen der springenwerk, blowenfusen und poppencorken mit spitzensparken. Ist nicht fuer gewerken bei das dumpkopfen. Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das pockets muss; relaxen und watchen das blinkenlichten.

Curses.Blinkenlights

Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights, but is designed to be run in a console window (an xterm, Linux virtual terminal, etc.) Since it doesn't have access to graphics, it isn't quite as pretty, but it still gets the job done.

Please see the Tk.Blinkenlights section above for more information about the colors used in this interface.

Tk.VerboseUI

Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface that presents a variable-sized window. In the window, each currently-executing thread has a section where its name and current status are displayed. This interface is best suited to people running on slower connections, as you get a lot of detail, but for fast connections, the detail may go by too quickly to be useful. People with fast connections may wish to use Tk.Blinkenlights instead.

TTY.TTYUI

TTY.TTYUI interface is for people running in basic, non-color terminals. It prints out basic status messages and is generally friendly to use on a console or xterm.

Noninteractive.Basic

Noninteractive.Basic is designed for situations in which OfflineIMAP will be run non-attended and the status of its execution will be logged. You might use it, for instance, to have the system run automatically and e-mail you the results of the synchronization. This user interface is not capable of reading a password from the keyboard; account passwords must be specified using one of the configuration file options.

Noninteractive.Quiet

Noninteractive.Quiet is designed for non-attended running in situations where normal status messages are not desired. It will output nothing except errors and serious warnings. Like Noninteractive.Basic, this user interface is not capable of reading a password from the keyboard; account passwords must be specified using one of the configuration file options.

Multiple Accounts with Mutt

This example shows you how to set up OfflineIMAP to synchronize multiple accounts with the mutt mail reader.

Start by creating a directory to hold your folders by running mkdir ~/Mail. Then, in your ~/.offlineimaprc, specify:

accounts = Personal, Work

Make sure that you have both an [Account Personal] and an [Account Work] section. The local repository for each account must have different localfolder path names. Also, make sure to enable [mbnames].

In each local repository section, write something like this:

localfolders = ~/Mail/Personal

Finally, add these lines to your ~/.muttrc:

source ~/path-to-mbnames-muttrc-mailboxes
folder-hook Personal set from="youremail@personal.com"
folder-hook Work set from="youremail@work.com"
set mbox_type=Maildir
set folder=$HOME/Mail
spoolfile=+Personal/INBOX

That's it!

UW-IMAPD and References

Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature to get at their mailboxes, specifying a reference of "~/Mail" or "#mh/" depending on the configuration. The below configuration from (originally from docwhat@gerf.org) shows using a reference of Mail, a nametrans that strips the leading Mail/ off incoming folder names, and a folderfilter that limits the folders synced to just three.

[Account Gerf]
localrepository = GerfLocal
remoterepository = GerfRemote

[Repository GerfLocal]
type = Maildir
localfolders = ~/Mail

[Repository GerfRemote]
type = IMAP
remotehost = gerf.org
ssl = yes
remoteuser = docwhat
reference = Mail
# Trims off the preceeding Mail on all the folder names.
nametrans = lambda foldername: \
            re.sub('^Mail/', '', foldername)
# Yeah, you have to mention the Mail dir, even though it
# would seem intuitive that reference would trim it.
folderfilter = lambda foldername: foldername in [
      'Mail/INBOX',
      'Mail/list/zaurus-general',
      'Mail/list/zaurus-dev',
      ]
maxconnections = 1
holdconnectionopen = no

pythonfile Configuration File Option

You can have OfflineIMAP load up a Python file before evaluating the configuration file options that are Python expressions. This example is based on one supplied by Tommi Virtanen for this feature.

In ~/.offlineimap.rc, he adds these options:

[general]
pythonfile=~/.offlineimap.py
[Repository foo]
foldersort=mycmp

Then, the ~/.offlineimap.py file will contain:

prioritized = ['INBOX', 'personal', 'announce', 'list']

def mycmp(x, y):
   for prefix in prioritized:
       xsw = x.startswith(prefix)
       ysw = y.startswith(prefix)
       if xsw and ysw:
          return cmp(x, y)
       elif xsw:
          return -1
       elif ysw:
          return +1
   return cmp(x, y)

def test_mycmp():
   import os, os.path
   folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
   folders.sort(mycmp)
   print folders

This code snippet illustrates how the foldersort option can be customized with a Python function from the pythonfile to always synchronize certain folders first.

UID validity problem for folder

IMAP servers use a unique ID (UID) to refer to a specific message. This number is guaranteed to be unique to a particular message forever. No other message in the same folder will ever get the same UID. UIDs are an integral part of OfflineIMAP's synchronization scheme; they are used to match up messages on your computer to messages on the server.

Sometimes, the UIDs on the server might get reset. Usually this will happen if you delete and then recreate a folder. When you create a folder, the server will often start the UID back from 1. But OfflineIMAP might still have the UIDs from the previous folder by the same name stored. OfflineIMAP will detect this condition and skip the folder. This is GOOD, because it prevents data loss.

You can fix it by removing your local folder and cache data. For instance, if your folders are under ~/Folders and the folder with the problem is INBOX, you'd type this:

rm -r ~/Folders/INBOX
rm -r ~/.offlineimap/Account-AccountName
rm -r ~/.offlineimap/Repository-RepositoryName

(Of course, replace AccountName and RepositoryName with the names as specified in ~/.offlineimaprc).

Next time you run OfflineIMAP, it will re-download the folder with the new UIDs. Note that the procedure specified above will lose any local changes made to the folder.

Some IMAP servers are broken and do not support UIDs properly. If you continue to get this error for all your folders even after performing the above procedure, it is likely that your IMAP server falls into this category. OfflineIMAP is incompatible with such servers. Using OfflineIMAP with them will not destroy any mail, but at the same time, it will not actually synchronize it either. (OfflineIMAP will detect this condition and abort prior to synchronization.)

This question comes up frequently on the OfflineIMAP mailing list. You can find a detailed discussion of the problem there.

Use with MS Exchange server

Several users have reported problems with Microsoft Exchange servers in conjunction with OfflineIMAP. This generally seems to be related to the Exchange servers not properly following the IMAP standards.

Mark Biggers has posted some information to the OfflineIMAP mailing list about how he made it work.

Other users have indicated that older (5.5) releases of Exchange are so bad that they will likely not work at all.

I do not have access to Exchange servers for testing, so any problems with it, if they can even be solved at all, will require help from OfflineIMAP users to find and fix.

Deleting Local Folders

OfflineIMAP does a two-way synchronization. That is, if you make a change to the mail on the server, it will be propagated to your local copy, and vise-versa. Some people might think that it would be wise to just delete all their local mail folders periodically. If you do this with OfflineIMAP, remember to also remove your local status cache (~/.offlineimap by default). Otherwise, OfflineIMAP will take this as an intentional deletion of many messages and will interpret your action as requesting them to be deleted from the server as well. (If you don't understand this, don't worry; you probably won't encounter this situation)

Multiple Instances

OfflineIMAP is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same mailbox simultaneously. It will perform a check on startup and abort if another OfflineIMAP is already running. If you need to schedule synchronizations, please use the autorefresh settings rather than cron. Alternatively, you can set a separate metadata directory for each instance.

Copying Messages Between Folders

Normally, when you copy a message between folders or add a new message to a folder locally, OfflineIMAP will just do the right thing. However, sometimes this can be tricky -- if your IMAP server does not provide the SEARCH command, or does not return something useful, OfflineIMAP cannot determine the new UID of the message. So, in these rare instances, OfflineIMAP will upload the message to the IMAP server and delete it from your local folder. Then, on your next sync, the message will be re-downloaded with the proper UID. OfflineIMAP makes sure that the message was properly uploaded before deleting it, so there should be no risk of data loss.

Use with Evolution

OfflineIMAP can work with Evolution. To do so, first configure your OfflineIMAP account to have sep = / in its configuration. Then, configure Evolution with the "Maildir-format mail directories" server type. For the path, you will need to specify the name of the top-level folder inside your OfflineIMAP storage location. You're now set!

Use with KMail

At this time, I believe that OfflineIMAP with Maildirs is not compatible with KMail. KMail cannot work in any mode other than to move all messages out of all folders immediately, which (besides being annoying and fundamentally broken) is incompatible with OfflineIMAP.

However, I have made KMail version 3 work well with OfflineIMAP by installing an IMAP server on my local machine, having OfflineIMAP sync to that, and pointing KMail at the same server.

Mailing List

There is an OfflineIMAP mailing list available. To subscribe, send the text "Subscribe" in the subject of a mail to offlineimap-request@complete.org. To post, send the message to offlineimap@complete.org. Archives are available at http://lists.complete.org/offlineimap@complete.org/.

Bugs

Reports of bugs should be sent via e-mail to the OfflineIMAP mailing list at offlineimap at complete dot org. Debian users are encouraged to instead use the Debian bug-tracking system.