Setting up a local IMAP cache with OfflineIMAP

Let’s assume you have one of these use cases:

  • limited bandwidth to your public mail server
  • polling / frequent automated access to email inboxes, e.g. by means of scripts
  • mailboxes with sensitive data that you would like to mirror / backup in almost real time

For these kinds of tasks, a local mail server in combination with a tool called „offlineimap“ is an easy to set up an low maintenance solution.

I’d like to share the basic setup from installing a mail server (Dovecot) and setting up offlineimap on a Linux system (I am using Ubuntu here, but the commands will only vary with regards to the package management commands, e.g. apt-get vs. yum). There is a lot of possibilities for tweaking and customizing, but following this guide will get you up and running quickly.

Install and configure Dovecot

Let’s first install the binaries:

sudo apt-get update
apt-get install dovecot-imapd

Now, let’s

  • disable authentication for local users (that is, users of the Linux system that Dovecot is running on)
  • enable authentication of „virtual“ users by using a text file with user and password information
  • adjust authentication configuration
  • switch Dovecot from MBox format to Maildir format

Open /etc/dovecot/conf.d/10-auth.conf with a text editor (I am using mcedit).

Comment this line:
# !include auth-system.conf.ext
Uncomment this line:
!include auth-passwdfile.conf.ext
Adjust these lines:
auth_mechanisms = plain login digest-md5 cram-md5
disable_plaintext_auth = no

Once finished, Dovecot will authenticate users against a file /etc/dovecot/users    So, let us create this file:

sudo touch /etc/dovecot/users
sudo chown root:dovecot users

Open /etc/dovecot/conf.d/10-mail.conf with a text editor. Change this parameter:

mail_location = maildir:/var/mail/%u/Maildir

With the MBox format, I was getting „Error: Opening INBOX failed: Mailbox isn’t selectable“. This gave me real headaches. I finally figured out that switching to the Maildir format solves this problem.

The local mail directory (the „cache“ if you will) needs to be owned by SOME local user on the Linux system, and we need its user and group ids:

id mylocaluser

Note the id for later. We will now set up a local Dovecot user. Edit the file /etc/dovecot/users and add ONE line for each mailbox:{PLAIN}mysecretpassword:1000:1000::/var/mail/

The syntax is <mailbox>:{PLAIN}<password>:<userid>:<groupid>::/var/mail/<mailbox>

Now, let us add both the local user and dovecot to the „mail“ group:

sudo usermod -a -G mail mylocaluser
sudo usermod -a -G mail dovecot

In the „users“ file, we specified a local directory where to keep the actual mails. We need to create this directory because Dovecot doesn’t do it automatically:

mkdir /var/mail/
chown -R root:mail /var/mail/
sudo chmod -R g+w /var/mail/
chmod -R a+rwxt /var/mail/

Finally, restart Dovecot:

sudo /etc/init.d/dovecot restart

Install and configure OfflineIMAP


sudo apt-get install offlineimap

OfflineIMAP will run as a user, not as root. We will use our sample „mylocaluser“ again. OfflineIMAP requires a file .offlineimaprc in the home directory of the user.

touch /home/mylocaluser/.offlineimaprc
Edit the file and use the following as template:

metadata = ~/.offlineimap.IMAP  
accounts = Account1  
maxsyncaccounts = 1  
ignore-readonly = no  
# ui = Quiet  

[Account Account1]  
# autorefresh = 5  

[Repository LocalIMAP1]  
type = IMAP  
# folderfilter = lambda foldername: foldername not in ['Trash']  
maxconnections = 10  

[Repository RemoteIMAP1]  
sslcacertfile = /etc/ssl/certs/ca-certificates.crt  
remotepass= mysecretpassword  
maxconnections = 2 
# folderfilter = lambda foldername: foldername not in ['Trash']

This will define a „RemoteIMAP1“ for your existing mailbox, and a LocalIMAP1 for your local Dovecot mailbox. Adjust user, host and password to your environment.

Once done, just run


as mylocaluser to perform an initial synchronization and check whether everything works.

Automatic synchronization

OfflineIMAP has a daemon mode that can run in the background. However, I found it to be too unstable / unreliable. I therefore use a script that runs as a cron job:

#!/usr/bin/env bash 
if pgrep offlineimap; then pkill offlineimap; sleep 10s; fi 
offlineimap -o -u quiet

Make the script executable and add it to the users crontab:

chmod a+x /home/mylocaluser/scripts/
crontab -e

This is the crontab line:

*/5 * * * * /home/mylocaluser/scripts/


This will perform a synchronization every 5 minutes. Done!

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.