How to Back Up an IMAP Mailbox

If your email is on Gmail, Outlook, iCloud, or another mail service, IMAP, or Internet Message Access Protocol, is a standard that lets mail apps read messages from the server and keep a copy in sync. When the mailbox changes, including when messages are deleted, the app updates its copy. So a synchronized copy on your computer alone is not a reliable backup. Thunderbird’s IMAP guidance explains why a separate copy matters.

For a local backup that is readable and easy to search, mailmd is the recommended choice. It copies messages into Markdown files, plain-text files that use simple markers for formatting, on your computer. Attachments are saved alongside them. You can keep that archive separately from your live mailbox and back it up like other files.

Create a local copy with mailmd #

mailmd is a free, open-source command-line tool. A command-line tool runs from a text-based terminal. It works with IMAP mailboxes. For Gmail and Outlook, it uses each provider’s API, a software interface for accessing an account. These providers often require different sign-in methods.

Install mailmd in a terminal:

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

Then connect the account using the method that matches your mailbox:

mailmd connect imap --email you@example.com
mailmd connect gmail --client-secret client_secret.json
mailmd connect outlook --client-id <id>

Use the first command for an IMAP mailbox, including Gmail with an app password. Gmail API access and Outlook access require your own OAuth app in Google Cloud or Microsoft Entra. An OAuth app lets you authorize access without giving the tool your ordinary account password. Some IMAP providers require an app password; mailmd indicates when one is needed.

Run the first copy with:

mailmd sync

By default, mailmd saves files under ~/mail/<account>. Each message becomes a Markdown file. Details such as the sender and subject appear at the top in a section called frontmatter. HTML messages become readable Markdown with links and tables. Attachments sit next to the message, and folders and years become directories. Add --keep-raw to save each original .eml message too.

mailmd only reads the mailbox: it requests read access and opens folders read-only. It does not mark messages as read, move or delete them, or send mail. Spam and trash are excluded unless requested. For Gmail over IMAP, it includes All Mail, so archived messages are included. Use --folder, --exclude, or --since to narrow what gets copied.

Keep the archive current and protected #

Run mailmd sync again to add new mail and update read and starred marks. If a sync stops, press Ctrl-C; the next run continues. To keep the archive current, set your computer’s scheduler, a tool that runs commands at set times, to run mailmd sync --quiet.

The archive stays separate from the live mailbox. mailmd never deletes files from the archive, so a message removed from the server stays there. mailmd marks it as deleted from the server. That protection depends on keeping the archive itself safe: copy it to a separate drive or offsite location, and retain dated copies rather than relying on one copy. General backup guidance recommends multiple copies and testing recovery.

Logins are stored outside the archive, unencrypted, and readable only by your user. Protect your computer and backup locations accordingly. mailmd has no search engine of its own; open the files in an editor or note app, or search them with rg or grep.

Check what the backup contains #

Open a few messages from different folders, including older mail, and open their attachments. Check that the folders you care about were included. For a raw-message copy, confirm that the corresponding .eml files are present.

A mailmd archive lets you read and preserve mail files. It does not act as an email program for managing your mailbox, import messages back into a mailbox, or free server storage. Delete messages from the email service only after confirming that the independent copy contains what you need.