Installation

Configuration

Offlineimap is distributed with two default configuration files, which are both located in /usr/share/offlineimap/. offlineimap.conf contains every setting and is thoroughly 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.

Selective folder synchronization

For synchronizing only certain folders, you can use a folderfilter in the remote section of the account in ~/.offlineimaprc. For example, the following configuration will only synchronize the folders Inbox and Sent:

Custom port

Some IMAP servers might require you to connect on a custom port, instead of the default 993 port. To do so, add a remoteport option to the remote section in ~/.offlineimaprc:

~/.offlineimaprc

[Repository main-remote]
remoteport=1234

Usage

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

$ mkdir ~/mail

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 did not bother with taking away tracebacks from the final product.

Tips and tricks

Running offlineimap in the background

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Maybe do not use a configuration file with comments as documentation, but describe them in the text? (Discuss in Talk:OfflineIMAP#)

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 = 0.5
# Quick-syncs do not update if the only changes were to IMAP flags.
# autorefresh=0.5 together with quick=10 yields
# 10 quick refreshes between each full refresh, with 0.5 minutes between every
# refresh, regardless of type.
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

To start the daemon automatically on login, start/enable the systemd/User service offlineimap.service using the --user flag.

In case you have more than one account configured, it is advised to use offlineimap@.service instead of increasing maxsyncaccounts parameter[1]. Simply start/enableofflineimap@youraccountname.service.

systemd timer

Alternatively, it is possible to manage OfflineIMAP completely using systemd-user timers, start/enable offlineimap-oneshot.timer with the --user flag.

This timer by default runs OfflineIMAP every 15 minutes. This can be easily changed by creating a drop-in snippet. For example, the following modifies the timer to check every 5 minutes:

~/.config/systemd/user/offlineimap-oneshot.timer.d/timer.conf

[Timer]
OnUnitInactiveSec=5m

The factual accuracy of this article or section is disputed.

Reason: This can lead to inconsistencies in the OfflineIMAP's local database. (Discuss in Talk:OfflineIMAP#)

For more robust solution it is possible to set a watchdog which will kill OfflineIMAP in case of freeze:

~/.config/systemd/user/offlineimap-oneshot.service.d/service.conf

[Service]
WatchdogSec=300

Automatic mailbox generation for mutt

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.

account is the name you have given to your IMAP account in ~/.offlineimaprc.

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:

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

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. If you do not want to make a reverse nametrans rule, you can disable remote folder creation by putting this in your remote configuration: createfolders = False

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 #SSL fingerprint does not match).

Password management

.netrc

Add the following lines to your ~/.netrc:

machine hostname.tld
login [your username]
password [your password]

Do not forget to give the file appropriate rights like 600 or 700:

$ chmod 600 ~/.netrc

Using GPG

GNU Privacy Guard can be used for storing a password in an encrypted file. First set up GnuPG and then follow the steps in this section. It is assumed that you can use your GPG private key without entering a password all the time.

First type in the password for the email account in a plain text file. Do this in a secure directory with 700 permissions located on a tmpfs to avoid writing the unencrypted password to the disk. Then encrypt the file with GnuPG setting yourself as the recipient.

Remove the plain text file since it is no longer needed. Move the encrypted file to the final location, e.g. ~/.offlineimappass.gpg.

Gnome keyring

In configuration for remote repositories the remoteusereval/remotepasseval fields can be set to custom python code that evaluates to the username/password. The code can be a call to a function defined in a Python script pointed to by 'pythonfile' config field. Create ~/.offlineimap.py according to either of the two options below and use it in the configuration:

If you created a password using seahorse, you can retrieve it from its description. For instance, the password for a repository Work which is stored in gnome-keyring with the description Password for me@myworkemail.com can be retrieved by adding the following to ~/.offlineimaprc:

For configurations where you wish to store the username as well, it is better if the password is created using secret-tool as this can be used to set attributes such as the username and repository name. Consider a password created with the following command:

[general]
# VVV Set this path correctly VVV
pythonfile = /home/user/offlineimap.py
...
[Repository RemoteEmail]
remoteuser = username@host.net
# Set the DB path as well as the title and username of the specific entry you would like to use.
# This will prompt you on STDIN at runtime for the kdb master password.
remotepasseval = get_keepass_pw("/path/to/database.kdb", title="<entry title>", username="<entry username>")
...

Note that as-is, this does not support KDBs with keyfiles, only KDBs with password-only auth.

Old kdb format

If your key database is stored in an old format, you the xpath strings may not be correct. This method should work in that case, but it is not compatible with the current default format (v4)

Install python2-keepass-gitAUR from the AUR, then add the following to your offlineimap.py file:

Kerberos authentication

Install python2-kerberosAUR 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.

Folder could not be created

In version 6.5.3, offlineimap gained the ability to create folders in the remote repository, as described here.

This can lead to errors of the following form when using nametrans on the remote repository:

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

Copying message, connection closed

Cause of this can be creation of same message both locally and on server. This happens if your email provider automatically saves sent mails to same folder as your local client. If you encounter this, disable save of sent messages in your local client.