mbsync and isync: Syncing IMAP Mail to Maildir

If you want a local copy of mail from an IMAP account, mbsync can synchronize server mailboxes with Maildir, a folder format that stores each message as a file. The isync project supplies the program: the package is named isync, and the command you run is mbsync. The settings determine whether mbsync copies changes only to your computer or also sends local changes back to the server, so choose them carefully.

mbsync suits people who want a local Maildir for a mail client or another tool. For a different kind of local copy, mailmd is a free, open source command-line alternative that saves email as readable, searchable Markdown files. The sections below explain how mbsync handles mail, how to test a configuration, and when mailmd fits better.

What mbsync copies #

mbsync connects to an IMAP server, which stores mailboxes online, and synchronizes selected mailboxes with local Maildir folders. It can copy new messages, propagate deletions, and update message flags such as read or starred status. Depending on the channel’s synchronization settings, those changes can travel from the server to the local Maildir, from the Maildir to the server, or in both directions. The mbsync manual describes these options and the program’s supported mailbox types.

The program tracks messages using unique identifiers, or UIDs, assigned by the IMAP server, and saves synchronization state in a local text file for each mailbox pair. On later runs, it compares the server mailbox with the local Maildir using that file, rather than relying only on message contents. Keep these state files with the Maildir when you make a backup: deleting one to clear an error can cause mbsync to download a mailbox again.

Maildir contains message files and supporting metadata. It is useful when a local mail client expects Maildir, or when another program needs to read individual messages in that format. It does not automatically make the local copy a safe one-way archive: a two-way configuration can send local deletions and flag changes back to the server.

Configure a channel and test it first #

The required configuration tells mbsync how to connect to the IMAP account, where to store local mail, which mailboxes to synchronize, and which changes to copy between them. It groups these settings into account, store, and channel definitions: an account holds connection details, a store describes a mailbox location, and a channel connects mailboxes to synchronize. The configuration file is mandatory. On current Arch Linux documentation, mbsync checks the XDG configuration location before falling back to ~/.mbsyncrc; other versions or distributions can use different defaults, so check the manual installed on your computer.

Choose where to put the local Maildir, then set the channel to synchronize only the folders you want. The Patterns setting selects mailboxes; the SubFolders setting tells mbsync how to represent nested IMAP folders inside Maildir. SubFolders has no default in the manual, and mbsync reports an error if it finds subfolders without an explicit setting.

Before transferring mail, use mbsync -l to list mailboxes without synchronizing. Then use mbsync -y channel-name to have it report planned actions without changing mailboxes or state files. Replace channel-name with the channel name in your configuration. Once the plan matches your intent, run mbsync channel-name.

For a cautious first setup, configure a pull-only sync, which copies changes from the server to the local Maildir. Inspect the result before enabling settings that push changes back or propagate deletions. The NeoMutt mbsync tutorial recommends testing with pull-only behavior before switching to a full two-way mirror.

Choose what happens to deletions and flags #

The Sync setting controls which changes mbsync copies between the server and the local Maildir. Options include pulling changes from the server, pushing local changes and synchronizing new messages. You can also set mbsync to propagate flags or deletions. The option names and defaults can vary between versions. For example, newer documentation uses Gone where an older FreeBSD manual uses Delete; check the manual for the version you installed rather than copying an old configuration unchanged.

Decide separately whether to copy deletions. To keep messages in your local copy after the server removes them, configure mbsync not to copy those deletions to the local Maildir. If you want changes on either side to appear on the other, first test a small selection of folders and check that changes copy correctly in both directions. Then expand the setup to all your mail.

A server can also change the UID validity value for a mailbox. That value tells the client whether its saved message identifiers still belong to the same mailbox state. mbsync documents recovery from some unfounded changes, but a change can still lead to unexpected re-synchronization. Avoid copying messages between Maildir folders while preserving their filenames: the manual warns that this can create duplicate UIDs under the native Maildir scheme.

Account for polling and server differences #

mbsync does not provide native IMAP IDLE support. IMAP IDLE lets a client keep a connection to the server open and receive a notification when new mail arrives. Because mbsync lacks IDLE, schedule it or use a separate notification tool to trigger it. The ArchWiki isync page describes this limitation and notes that a scheduled sync also catches messages that arrived while the computer was offline.

Server behavior can affect performance and compatibility. The manual describes STARTTLS on port 143 as the usual default when no tunnel is used; check your provider’s IMAP settings before changing transport options. The ArchWiki also notes that Gmail TLS 1.3 requires isync 1.3.0 or later because Google enforces SNI, a TLS feature that identifies the server name during the connection. If a provider rejects pipelined IMAP commands, which a client sends without waiting for a reply to each one, setting PipelineDepth 1 has resolved problems on some servers. This setting reduces throughput.

Authentication needs particular care with Gmail and other providers. Gmail setups have used app passwords, while OAuth-based access depends on the installed mbsync version and its SASL support. Providers change their rules and available methods. Before choosing how to authenticate, check your provider’s current instructions and the documentation for your installed version.

When mailmd fits better #

Use mbsync when another mail client needs Maildir or you want synchronization that can carry changes in both directions. Use mailmd when you want a folder of message files you can read and search without a Maildir-aware mail client. Each message becomes a Markdown file with its headers in frontmatter; attachments sit next to the message, and folders and years become directories. HTML mail is converted to readable Markdown, while tracking images and hidden preview text are removed.

mailmd opens mailbox folders read-only and requests read access. It does not mark server mail as read, move or delete messages, or send mail. mailmd adds new messages to the local archive and updates their read and starred marks each time you sync. It never removes archived files. If someone deletes a message on the server, mailmd keeps it in the archive and marks it as deleted there. Spam and trash stay out unless requested. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages.

To try mailmd with an IMAP account, install it and run:

curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh
mailmd connect imap --email you@example.com
mailmd sync

The resulting files go under ~/mail/<account>. To connect through the Gmail API or to Outlook.com and other Microsoft mail services, use separate commands and your own OAuth app. See the mailmd project for connection details. Use tools such as rg or grep to search the files, or use jq to filter index.jsonl. mailmd has no built-in search engine and does not import mail back into a mailbox, convert it to PST or PDF, or free server storage by itself.