OfflineIMAP vs Nylas: Python IMAP sync

Command references used in this guide: nylas email list, nylas email search, and nylas init.

What is OfflineIMAP?

OfflineIMAP is a Python program that synchronizes an IMAP account to a local Maildir, in one or two directions. Like mbsync it is a sync engine, not a reader: it puts mail on disk so a separate client opens it. Its distinguishing feature is that ~/.offlineimaprc can call out to Python through a pythonfile, so password and OAuth logic lives in real code rather than a static directive.

The project shifted after Python 2 reached end of life on January 1, 2020. The original OfflineIMAP was Python 2; the maintained fork, offlineimap3, targets Python 3. It pairs with the same readers as any Maildir tool — mutt, neomutt, or notmuch — and with msmtp for sending, since OfflineIMAP only handles the receiving half.

How do you sync Gmail with OfflineIMAP?

Syncing Gmail with OfflineIMAP means defining a remote IMAP repository for imap.gmail.com and a local Maildir repository, then linking them in an account stanza. Gmail blocks plain passwords over IMAP, so you authenticate with OAuth2 — OfflineIMAP supports it directly through oauth2_request_url, oauth2_client_id, and a refresh token — or fall back to a 16-character app password.

OfflineIMAP is more flexible here than mbsync because the credential can be computed in Python at runtime. The cost is speed: OfflineIMAP is widely reported to sync large Gmail mailboxes more slowly than the C-based mbsync, and the first full sync still downloads every message to disk before you read anything.

# ~/.offlineimaprc — Gmail to a local Maildir
[general]
accounts = gmail

[Account gmail]
localrepository = gmail-local
remoterepository = gmail-remote

[Repository gmail-local]
type = Maildir
localfolders = ~/Mail/gmail

[Repository gmail-remote]
type = Gmail
remoteuser = you@gmail.com
# OAuth2 (preferred) — values come from a Google Cloud OAuth client:
auth_mechanisms = XOAUTH2
oauth2_client_id = <client-id>
oauth2_client_secret = <client-secret>
oauth2_request_url = https://accounts.google.com/o/oauth2/token
oauth2_refresh_token = <refresh-token>
# ...or auth_mechanisms = LOGIN with an app password instead.

OfflineIMAP vs an API-backed email CLI

OfflineIMAP wins when you need a Python-controlled Maildir mirror; an API-backed CLI wins when the mailbox should stay remote. The table compares the work each path asks you to own: runtime hooks, first-sync cost, auth setup, and what a script receives after 1 command.

When should you still use OfflineIMAP?

OfflineIMAP earns its place when you want an offline Maildir and need credential logic that a static config can't express. Because the pythonfile hook runs real Python, you can pull a token from a secrets manager, rotate it, or compute a password however your environment requires — then read the synced Maildir with no network at all.

It also suits people already invested in a Maildir workflow who prefer Python tooling to the C of mbsync. The same local mailbox feeds your reader, a notmuch index, and your backups. If full offline ownership and scriptable credential handling are the goal, OfflineIMAP remains a reasonable pick despite its slower syncs.

How does the API approach skip the sync step?

The API path removes OfflineIMAP's two slowest steps: the Python sync process and the first local mirror. After nylas init, nylas email list and nylas email search ask the live mailbox for the next page over HTTPS, so a 50,000-message account does not have to land on disk before the first read.

That changes the failure mode. You trade OfflineIMAP's offline Maildir and pythonfile token logic for one OAuth grant that also reaches calendar and contacts. Scripts get JSON directly instead of walking Maildir files. If the network is down, OfflineIMAP's local copy wins; if setup speed matters, the API path is shorter.

# One OAuth login — no .offlineimaprc, no Maildir, no Python stanza
nylas init

# Read the live inbox over HTTPS (no first-sync download)
nylas email list --limit 20

# Search server-side and pipe structured output into scripts
nylas email search "invoice" --after 2026-01-01 --json | jq -r '.[].subject'

Choose OfflineIMAP for an offline Maildir with scriptable, Python-based credential handling. Reach for the API-backed CLI when one OAuth login beats running a sync daemon. The mbsync vs Nylas comparison covers the faster C-based synchronizer, and neomutt vs aerc covers the readers that sit on top of a synced Maildir.

Next steps

• mbsync vs Nylas — the C-based sync engine compared to API access
• Read email from the terminal — the nylas email list and TUI walkthrough
• Best CLI email tools compared — the wider field of terminal mail tools ranked
• List Gmail emails from the CLI — Gmail without an IMAP app password
• Full command reference — every flag and subcommand documented