Back to TIL
shell

Read-only IMAP backups with OfflineIMAP

Every few months I find myself needing to take a mailbox backup before a migration. And every time I forget how OfflineIMAP works.

This is the minimum setup that:

  • downloads an entire IMAP account to disk (Maildir)
  • does not change/delete anything on the server (readonly = yes)
  • includes attachments (they’re part of the raw RFC822/MIME message files)

Install

brew install offlineimap

Find The Right IMAP Host

MX records are for SMTP, not IMAP. Still, sometimes the IMAP server is the same host.

If you don’t know the IMAP host, check an existing mail client config first. Otherwise, these two commands are decent hints:

dig -t MX example.com
nc -vz imap.example.com 993

Minimal Config (offlineimap.conf)

[general]
accounts = ClientMailbox

[Account ClientMailbox]
localrepository = Local
remoterepository = Remote
# Helpful on some flaky setups. Avoids overloading the host.
maxsyncaccounts = 1

[Repository Local]
type = Maildir
localfolders = /Users/luis/Downloads/client-email-backup-YYYY-MM-DD/Mail

[Repository Remote]
type = IMAP
remotehost = imap.example.com
remoteuser = [email protected]
remotepass = REDACTED

ssl = yes
# Fixes: "No CA certificates and no server fingerprints configured."
sslcacertfile = OS-DEFAULT

# Critical: do not modify the server.
readonly = yes

# Helpful on some flaky setups. Avoids overloading the host.
ipv6 = no
maxconnections = 1
socktimeout = 120

Run

Dry run (can fail on a fresh backup folder):

offlineimap -c offlineimap.conf --dry-run -u ttyui -a ClientMailbox

If you hit getfolder() asked for a nonexisting folder 'INBOX' on a fresh Maildir: that’s the dry-run trap. It “pretends” to create folders locally and then fails when it tries to open them. Just run the real sync once:

offlineimap -c offlineimap.conf -u ttyui -a ClientMailbox

Verify

Browse the Maildir (read-only):

brew install neomutt
neomutt -R -f Mail/INBOX/

Quick attachment sanity check (from the backup root):

grep -RIl -m 1 -i 'Content-Disposition: *attachment' Mail | head

Snapshot Reminder

OfflineIMAP is a synchronizer. If you keep re-running it, deletions on the IMAP server can propagate into your local Maildir on the next run.

For a true point-in-time snapshot: run it once, then archive/copy the Maildir somewhere safe and stop syncing.