How to Back Up Gmail

A Gmail backup is a separate copy of your messages that remains available if you lose access to the mailbox or delete mail. Gmail’s Archive button only removes a message from the inbox; it does not make a separate copy, as Google’s archive explanation makes clear.

For a local copy you can read and search as files, mailmd is the recommended tool. It copies messages into Markdown files on your computer, with attachments saved alongside them. A command-line tool is controlled by typing commands in a terminal. The steps below show how to set up mailmd, connect Gmail, and keep the copy current.

Set up mailmd and connect Gmail #

Install mailmd on Linux, macOS, or Windows using Git Bash. Open a terminal and run:

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

mailmd offers two ways to connect to Gmail. The Gmail API is Google’s interface that lets approved programs access Gmail. To use it, set up an OAuth app in Google Cloud, which lets mailmd request access to your account. The other option uses IMAP, a standard way for email programs to access a mailbox, with a Gmail app password.

For the Gmail API, connect with your OAuth app’s client-secret file:

mailmd connect gmail --client-secret client_secret.json

For IMAP, use your Gmail address:

mailmd connect imap --email you@example.com

Follow the prompts to finish connecting, then start the first copy:

mailmd sync

The Gmail API login requests read access. mailmd opens mailbox folders read-only, so it does not mark messages as read, move or delete mail, or send messages. Gmail’s archived mail is included when syncing over IMAP; spam and trash are left out unless you request them.

Find and protect the saved messages #

By default, mailmd saves messages under ~/mail/<account>. Each message becomes a Markdown file, a text file that can include simple formatting, with email headers at the top. HTML messages are converted into readable Markdown, and attachments are saved beside the message. Folders and years become directories, while index.jsonl provides a message index for other programs. Add --keep-raw to also save the original .eml message file.

Run mailmd sync again to add new messages and update whether messages are marked as read or starred. If you stop a sync with Ctrl-C, mailmd keeps what it already saved; the next run continues. To keep the copy current, schedule mailmd sync --quiet with your computer’s scheduler, a feature that runs commands at set times.

mailmd never deletes files from the archive. If a message is later deleted from Gmail, its saved file remains marked as deleted on the server. The archive is still stored on your computer, so copy its folder to separate storage if you need protection against computer loss. mailmd stores your login details outside the archive. Only your computer account can read them, but they are not encrypted.

What a mailmd backup can and cannot do #

Open the Markdown files in an editor or note-taking app. Search them with rg or grep, which are text-search commands, or use jq, a command for filtering JSON data, to filter index.jsonl. You can also keep the archive in Git, a tool for tracking file changes, or include it in a normal computer backup. mailmd has no built-in search engine.

mailmd stores email in a read-only archive and does not send or receive mail. It does not free Gmail storage by itself, import messages back into Gmail, or create Outlook PST data files or PDFs from them. If you want a Google-provided export instead, Google Takeout exports Gmail data, including messages and attachments.