Installing

Configuring

Offlineimap is distributed with two default configuration files, which are both located in /usr/share/offlineimap/. offlineimap.conf contains every setting and is thorougly documented. Alternatively, offlineimap.conf.minimal is not commented and only contains a small number of settings (see: Minimal).

Copy one of the default configuration files to ~/.offlineimaprc.

Note: Writing a comment after an option/value on the same line is invalid syntax, hence take care that comments are placed on their own separate line.

Minimal

The following file is a commented version of offlineimap.conf.minimal.

Usage

Before running offlineimap, create any parent directories that were allocated to local repositories:

$ mkdir ~/Maildir

Now, run the program:

$ offlineimap

Mail accounts will now be synced. If anything goes wrong, take a closer look at the error messages. OfflineIMAP is usually very verbose about problems; partly because the developers didn't bother with taking away tracebacks from the final product.

Miscellaneous

Various settings and improvements

Running offlineimap in the background

Most other mail transfer agents assume that the user will be using the tool as a daemon by making the program sync periodically by default. In offlineimap, there are a few settings that control backgrounded tasks.

Confusingly, they are spread thin all-over the configuration file:

~/.offlineimaprc

# In the general section
[general]
# Controls how many accounts may be synced simultaneously
maxsyncaccounts = 1
# In the account identifier
[Account main]
# Minutes between syncs
autorefresh = 5
# Number of quick-syncs between autorefreshes. Quick-syncs do not update if the
# only changes were to IMAP flags
quick = 10
# In the remote repository identifier
[Repository main-remote]
# Instead of closing the connection once a sync is complete, offlineimap will
# send empty data to the server to hold the connection open. A value of 60
# attempts to hold the connection for a minute between syncs (both quick and
# autorefresh).This setting has no effect if autorefresh and holdconnectionopen
# are not both set.
keepalive = 60
# OfflineIMAP normally closes IMAP server connections between refreshes if
# the global option autorefresh is specified. If you wish it to keep the
# connection open, set this to true. This setting has no effect if autorefresh
is not set.
holdconnectionopen = yes

systemd Service

Writing a systemd service for offlineimap is trivial, just be sure to run it as the correct user by replacing the User=UserToRunAs with your user. (e.g. User=wgiokas)

The wrapper script is needed because offlineimap has the tendency to sporadically crash, even more so when facing connection problems.

Automatic mutt mailbox generation

Mutt cannot be simply pointed to an IMAP or maildir directory and be expected to guess which subdirectories happen to be the mailboxes, yet offlineimap can generate a muttrc fragment containing the mailboxes that it syncs.

Gmail configuration

This remote repository is configured specifically for Gmail support, substituting folder names in uppercase for lowercase, among other small additions. Keep in mind that this configuration does not sync the All Mail folder, since it is usually unnecessary and skipping it prevents bandwidth costs:

Note: If you have Gmail set to another language, the folder names may appear translated too, e.g. "verzonden_berichten" instead of "sent_mail".

Note: After version 6.3.5, offlineimap also creates remote folders to match your local ones. Thus you may need a nametrans rule for your local repository too that reverses the effects of this nametrans rule.

Note: As of 1 October 2012 gmail SSL certificate fingerprint is not always the same. This prevents from using cert_fingerprint and makes the sslcacertfile way a better solution for the SSL verification (see OfflineIMAP#SSL fingerprint does not match).

Emacs EasyPG

Kerberos authentication

Install python2-kerberos from AUR and do not specify remotepass in your .offlineimaprc.
OfflineImap figure out the reset all if have a valid Kerberos TGT.
If you have 'maxconnections', it will fail for some connection. Comment 'maxconnections' out will solve this problem.

Troubleshooting

Overriding UI and autorefresh settings

For the sake of troubleshooting, it is sometimes convenient to launch offlineimap with a more verbose UI, no background syncs and perhaps even a debug level:

$ offlineimap [ -o ] [ -d <debug_type> ] [ -u <ui> ]

-o

Disable autorefresh, keepalive, etc.

-d <debug_type>

Where <debug_type> is one of imap, maildir or thread. Debugging imap and maildir are, by far, the most useful.

-u <ui>

Where <ui> is one of CURSES.BLINKENLIGHTS, TTY.TTYUI, NONINTERACTIVE.BASIC, NONINTERACTIVE.QUIET or MACHINE.MACHINEUI. TTY.TTYUI is sufficient for debugging purposes.

Note: More recent versions use the following for <ui>: blinkenlights, ttyui, basic, quiet or machineui.

Curses interface (Curses.Blinkenlights) locks terminal

Because of a bug in Python's ncurses package (http://bugs.python.org/issue7567) the Curses interface of OfflineIMAP breaks the terminal on exit.
While it appears to irreparably lock the terminal, in reality it only prevents commands from being displayed.
The bug has been fixed in Python's SVN for all versions 2.6 up to 3.2 but the current package in the repositories (Python 2.6.5) is still buggy.

In order to solve the issue:

either append reset to OfflineIMAP's launch command:

$ offlineimap; reset

or change the ui field in ~/.offlineimaprc to select a fully functional one:

ui = TTY.TTYUI

or as quick workaround you can just use the following command to skip the reset() function in Curses.py which causes the problem

netrc authentication

There are some bugs in the current offlineimap which makes it impossible to read the authentication data from ~/.netrc if there are multiple Accounts per remote machine. ( see Mail Archive ) But they are fixed in the GIT package offlineimap-gitAUR (note that is AUR package is flagged as out of date; see the current GitHub external link below).
Using the package you can collect all passwords in ~/.netrc. And do not forget to set it's access rights:

chmod 600 ~/.netrc

An example netrc file would be

~/.netrc

machine mail.myhost.de
login mr_smith
password secret

socket.ssl deprecation warnings

Depending on the currently installed python version, running offlineimap throws this warning:

For working out the correct inverse mapping. the output of offlineimap --info should help.

After updating the mapping, it may be necessary to remove all of the folders under $HOME/.offlineimap/ for the affected accounts.

SSL fingerprint does not match

ERROR: Server SSL fingerprint 'keykeykey' for hostname 'example.com' does not match configured fingerprint. Please verify and set 'cert_fingerprint' accordingly if not set yet.

To solve this, add to ~/.offlineimaprc (in the same section as ssl = yes) one of the following:

either add cert_fingerprint, with the certificate fingerprint of the remote server. This checks whether the remote server certificate matches the given fingerprint.

cert_fingerprint = keykeykey

or add sslcacertfile with the path to the system CA certificates file. Needs ca-certificates installed. This validates the remote ssl certificate chain against the Certification Authorities in that file.

sslcacertfile = /etc/ssl/certs/ca-certificates.crt

External links

This setup worked for me, only difference being I had to add mail_location = maildir:~/Maildir to /etc/dovecot/dovecot.conf. Also, I used the Gmail configuration above. --Unhammer 09:24, 22 October 2010 (EDT)