How to Back Up a Very Large Mailbox Without Starting Over

Copying a large mailbox can take a long time. If a backup stops, you do not have to repeat the work. Keep the files already saved, then use a tool that adds new messages each time you run it. That approach is called an incremental backup: each run builds on the existing copy instead of making a fresh one.

mailmd is a free, open-source command-line tool for doing this. It saves messages as Markdown files on your computer and keeps the archive when a run stops. A command-line tool runs through text commands in a terminal, rather than a graphical window.

Keep the saved messages and continue syncing #

Do not delete a partial archive before troubleshooting. Some backup methods save progress information with the messages. Deleting the archive or that information can make it harder to continue without creating duplicates.

With mailmd, sync adds new mail to the existing archive. If you stop a run with Ctrl-C, mailmd keeps the messages it has already saved; the next run continues syncing. This preserves completed messages, though it does not promise to resume an individual message transfer partway through.

Mailbox changes leave the archive unchanged. mailmd never deletes archive files. If a message is later deleted from the mail server, its saved file remains and is marked as deleted on the server.

Back up a mailbox with mailmd #

Install mailmd, connect your account, and sync the mailbox. mailmd saves the files in ~/mail/<account>.

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

Choose the connection command for the mailbox:

# IMAP mailboxes, including Gmail with an app password
mailmd connect imap --email you@example.com

# Gmail through the Gmail API
mailmd connect gmail --client-secret client_secret.json

# Outlook.com or Microsoft 365 through Microsoft Graph
mailmd connect outlook --client-id <id>

IMAP is a standard way for email programs to access mail stored on a server. Many providers require an app password for IMAP; mailmd indicates when one is needed. Connecting through Gmail API or Microsoft Graph requires an OAuth app and account authorization setup in Google Cloud or Microsoft Entra. Outlook.com and Microsoft 365 use Microsoft Graph because most Outlook mailboxes no longer accept IMAP passwords.

Run this command to start or continue copying mail:

mailmd sync

mailmd opens folders read-only and requests read access. It does not mark messages as read or change or move server mail. It also does not send messages. mailmd saves each message as a Markdown file with its headers and readable text. It saves attachments as separate files alongside it. HTML messages are converted to readable Markdown; --keep-raw also saves the original .eml file.

By default, spam and trash are excluded. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages. Use --folder, --exclude, or --since to choose what to copy. Check those choices before treating the archive as complete. After the first run, set up a scheduler to run mailmd sync --quiet and keep the copy current. Options include cron, launchd, and Task Scheduler.

Check the archive and protect it separately #

Open a few saved files from different folders and years, including messages with attachments. The archive includes an index.jsonl file listing messages for scripts. To find text, use an editor or a command such as rg or grep; mailmd does not include its own search engine.

Keep another copy of the archive in a normal backup location. A local mailbox copy protects against server-side deletion, but it does not protect against losing the computer or archive folder. CISA and partner agencies recommend maintaining backups and testing that they can be restored.

mailmd stores login details outside the archive. The files are not encrypted, but only your computer user can read them. mailmd does not free space in the online mailbox or restore mail to a mailbox. It also does not create PST or PDF files from messages. Delete server mail only after checking that the local copy contains what you need.