Guide

mbsync vs Nylas: IMAP sync vs email API

mbsync (isync) is a sync engine, not a mail client: it mirrors an IMAP account into a local Maildir that mutt, neomutt, or notmuch then read. That design gives you a full offline archive at the cost of an IMAP connection, an XOAUTH2 SASL plugin for Gmail, and a multi-gigabyte first sync. This compares the mbsync stack against an API-backed CLI that reads the same inbox over HTTPS with no local mirror.

Written by Caleb Geene Director, Site Reliability Engineering

Verified — CLI 3.1.24 · Gmail, Outlook · last tested June 23, 2026

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

What is mbsync (isync)?

mbsync is a command-line IMAP synchronizer: it copies messages between a remote IMAP server and a local Maildir, in one or both directions. It is the binary that the isync project ships, and it has been maintained since the early 2000s. mbsync is not a reader — it moves mail to disk so a separate client can open it.

The full stack is modular by design. mbsync handles the download, msmtp handles sending, and mutt, neomutt, or notmuch handles reading and search. Each tool does one job and is configured in its own file. The payoff is a complete offline archive: once synced, you can read and search 50,000 messages with no network at all.

How do you sync Gmail with mbsync?

Syncing Gmail with mbsync means writing a ~/.mbsyncrc channel that points at imap.gmail.com:993 and authenticating the connection. Gmail no longer accepts a plain password over IMAP, so you supply either a 16-character app password under 2-Step Verification, or OAuth through the cyrus-sasl-xoauth2 SASL plugin plus an external token-refresh script.

The AuthMechs XOAUTH2 path is the fiddly part. The plugin has to be compiled and discoverable by Cyrus SASL, and you maintain a helper that exchanges a refresh token for an access token on each run. The first sync of a large Gmail account downloads every message into Maildir, which can mean several gigabytes on disk before you read a single line.

# ~/.mbsyncrc — Gmail to a local Maildir
IMAPAccount gmail
Host imap.gmail.com
Port 993
User you@gmail.com
# App password under 2-Step Verification:
PassCmd "pass show gmail-app-password"
# ...or OAuth via the cyrus-sasl-xoauth2 plugin:
# AuthMechs XOAUTH2
# PassCmd "/path/to/oauth2-token.sh you@gmail.com"
SSLType IMAPS

IMAPStore gmail-remote
Account gmail

MaildirStore gmail-local
Path ~/Mail/gmail/
Inbox ~/Mail/gmail/INBOX

Channel gmail
Far :gmail-remote:
Near :gmail-local:
Patterns "*"

mbsync vs an API-backed email CLI

mbsync wins on offline access and full local ownership; an API-backed CLI wins on setup, auth, and breadth. The table contrasts the two approaches across the decisions that matter when you choose how a terminal reaches your mail. The mbsync column assumes the usual mbsync + msmtp + neomutt stack.

Dimensionmbsync stacknylas email
RoleSync engine (needs a reader)Reader + sender in one
TransportIMAP to local MaildirNylas API (HTTPS)
Gmail authApp password / XOAUTH2 pluginOAuth (built in)
First syncDownloads full mailbox to diskNone — reads live
Offline accessYes (full Maildir)No (needs network)
Calendar / contactsEmail onlySame grant covers both
Scriptable outputParse Maildir files yourself--json on every command

When should you still use mbsync?

mbsync is the right tool when offline access and local ownership are the point. If you need every message on disk in standard Maildir format — for air-gapped reading, a permanent archive, or fast local full-text search through notmuch — mbsync does that better than any API client. A Maildir is just files, so it outlives any single vendor and survives without a network.

The stack also suits people who already live in mutt or neomutt and want one sync daemon feeding several tools. mbsync runs fine from cron or a systemd timer every few minutes, and the same Maildir feeds your reader, your search index, and your backup. That composability is the classic Unix-mail argument, and it holds.

How does the API approach skip the sync step?

The Nylas CLI reads mail through the Nylas API over HTTPS, so there is no Maildir to sync and no SASL plugin to compile. You authenticate once with nylas init over OAuth, and the token refreshes every 3,600 seconds. The inbox stays on the server; nylas email list and nylas email search page through it on demand instead of mirroring it to disk first.

Because the same grant also reaches calendar and contacts, one auth covers three data types that an mbsync stack cannot — mbsync is IMAP-only and never sees your calendar. And every command emits --json, so the inbox you skim interactively is the inbox a script or AI agent reads. The honest trade-off: there is no offline Maildir, and a network outage means no mail.

# Authenticate once over OAuth — no .mbsyncrc, no Maildir, no SASL plugin
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 "*" --from billing@example.com --json | jq -r '.[].subject'

Choose mbsync when you want a local Maildir you fully own and can read offline. Reach for the API-backed CLI when the IMAP sync, app-password rotation, and XOAUTH2 plumbing cost more than the offline copy is worth. The neomutt vs aerc comparison covers the readers that sit on top of an mbsync Maildir.

Next steps