OfflineIMAP: Syncing IMAP Mail to Local Folders

When you want to read mail offline, OfflineIMAP connects to a mail server using IMAP, the protocol mail clients use to access server mail, and copies and synchronizes mail into a local Maildir folder. Maildir stores each message in a separate file. Compatible mail readers can open these files without connecting to the server. OfflineIMAP syncs changes between the server and the local folder. If you delete a message locally, OfflineIMAP can also delete it from the server.

If you want a read-only archive of files you can read and search, mailmd is a free, open source alternative. It saves each message as a Markdown file and leaves the mailbox unchanged. Choose OfflineIMAP if you need a Maildir that a compatible mail reader can use. Choose mailmd if you want an archive of files.

How OfflineIMAP stores and syncs mail #

Each OfflineIMAP account links two places where mail is stored. One side must be an IMAP server; the other can be a local Maildir or another IMAP server. OfflineIMAP compares the two stores and syncs messages and their flags, such as whether a message is read or starred. This two-way sync lets a mail reader work with the local Maildir, but it also sends local changes to the server.

A Maildir stores messages in a directory tree instead of one mailbox file. OfflineIMAP keeps local message files there, and a compatible mail user agent, or MUA, can read them offline. The project documentation describes OfflineIMAP as a way to download IMAP mail for offline use.

OfflineIMAP uses folder and message IDs from IMAP to track mail between syncs. A folder’s UIDVALIDITY value identifies the current set of message IDs in that folder. If the server changes this value, OfflineIMAP skips the folder to avoid matching the wrong messages. Its FAQ explains how moving the cache aside forces a full resync when needed.

Configure and run a sync #

Follow the OfflineIMAP quick start to set up an account with one repository for the remote IMAP server and another for the local Maildir. Then run OfflineIMAP with that account’s configuration file. The first sync downloads the mail already on the server. Later runs compare the two stores and transfer changes.

Before changing either store, run --dry-run to see what OfflineIMAP would do without making changes. The option lists the planned actions, but does not report how many messages it would transfer. The Debian offlineimap3 manual documents this and other command-line options.

You can choose which folders OfflineIMAP syncs. OfflineIMAP’s folderfilter setting selects folders by name. Its nametrans setting changes folder names as they pass between the server and local store. Use --info to inspect folder transformations without changing mail; the folder filtering documentation describes how these settings work. Use these settings when your provider shows folders you do not want on your computer, or when folder names differ between the server and local store.

Understand deletion and quick sync behavior #

Treat the local Maildir as a mailbox that syncs with the server. It does not automatically protect messages from deletion. If you remove local message files, OfflineIMAP can also delete those messages from the server. The FAQ documents sync_deletes = no as a setting that prevents deletions from being propagated. Before clearing a local folder, check whether OfflineIMAP will also delete its messages from the server.

Use -q to run a quick sync. Compared with a regular sync, it checks fewer details on the server. As a result, OfflineIMAP can miss changes to message flags made on the server, such as marking a message as read on another device. Run a full sync when you want OfflineIMAP to check message flags on the server too.

Give each IMAP account its own local Maildir. The manual warns that if different IMAP servers have overlapping message IDs, using the same local Maildir root for both can cause upload loops or missed messages.

Check the Python version and connection security #

The original OfflineIMAP GitHub repository is marked as a legacy Python 2 project and directs Python 3 users to offlineimap3. Check which implementation your package includes, then follow its documentation. Instructions for one version might not apply to another.

Check connection security before syncing. The original OfflineIMAP documentation warns that its default settings do not verify server certificates. Without this check, an attacker could intercept and alter the connection in a man-in-the-middle attack. The documentation describes how to set sslcacertfile to verify certificates. It also warns that STARTTLS does not verify the server certificate. Before entering mailbox credentials, check the security settings for the implementation you installed.

According to the manual, the -d imap debug option can include passwords in its output. Before sharing debug logs, remove credentials and any other sensitive data.

When mailmd is the better fit #

Use OfflineIMAP if you want a local Maildir for a compatible mail client and want changes to sync between the local folder and the server. Use mailmd if you want a read-only archive of individual message files to search, process with scripts, or read in an editor. mailmd saves message headers as Markdown frontmatter and formats HTML mail as readable Markdown. It stores attachments beside the messages. It keeps a message index in index.jsonl. mailmd does not delete archive files when messages disappear from the server.

mailmd works with IMAP mailboxes. It also connects to Gmail through the Gmail API and to Outlook.com through Microsoft Graph. To use those API connections, you need your own OAuth app. Its repository documents installation and setup. Choose mailmd if you want a copy made of files and do not need a Maildir that syncs changes back to the mailbox.

$ curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh

Set up mailmd so you can read my email. Use https://github.com/vincentsch/mailmd: read its AGENTS.md and follow the steps. Connect my mailbox and run the first sync. Then show me where the files are.