A Free Gmail Backup Tool That Saves Your Mail as Markdown: mailmd

Gmail keeps your messages on Google’s servers. A separate copy gives you files you can keep on your computer and search without opening Gmail. mailmd is a free, open-source command-line tool that copies email into Markdown files, a plain-text format that people can read and edit with many editors and note apps.

Each message gets its own file, with message details such as the sender and date at the top. mailmd connects to Gmail through the Gmail API or through IMAP, a standard way for email programs to access a mailbox. The result is a local archive you can search and back up alongside other files.

Set up mailmd for Gmail #

Install mailmd from a terminal with:

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

Choose one of two ways to connect Gmail. The Gmail API option uses an OAuth app, a registration in Google Cloud that lets mailmd request permission to read your mail. The IMAP option uses Gmail’s IMAP access and an app password, a separate password some mail providers require for mail programs.

For the Gmail API, create the OAuth app and its client secret in Google Cloud, then connect with the downloaded secret file:

mailmd connect gmail --client-secret client_secret.json

For IMAP, use:

mailmd connect imap --email you@example.com

mailmd tells you if your provider requires an app password. After connecting, copy the messages with:

mailmd sync

The archive goes in ~/mail/<account>. On Windows, mailmd runs in Git Bash. It also works on macOS and Linux. If you prefer a coding agent, you can ask it to set up mailmd using the instructions in the project repository; type your password directly into mailmd so the agent does not see it.

What the Gmail archive contains #

mailmd saves one Markdown file per message. Message headers, such as sender and subject, appear at the top as frontmatter, a block of metadata stored before the message text. mailmd turns formatted HTML email into readable Markdown while keeping links and tables. Tracking images and hidden preview text are removed. Attachments sit next to their message files, while folders and years become directories. An index.jsonl file lists messages for scripts, and --keep-raw also saves each original message as an .eml file.

For Gmail accessed over IMAP, mailmd syncs All Mail, which includes archived messages. Spam and Trash stay out unless requested. Use --folder, --exclude, or --since to choose what to copy.

Each sync adds new messages and updates whether saved messages are marked as read or starred. It does not mark messages as read in Gmail. If you stop a sync with Ctrl-C, mailmd keeps the files already saved, and the next run continues. Mail deleted later in Gmail remains in the local archive with a mark showing that it was deleted on the server. mailmd never deletes archive files.

Keep the copy current and protect it #

Run mailmd sync --quiet on a schedule to update the archive. On a computer that supports scheduled commands, you can use cron or systemd on Linux, launchd on macOS, or Task Scheduler on Windows.

The archive is stored on your computer, but the login details are a separate security consideration: mailmd saves them outside the archive, unencrypted, with access limited to your user account. mailmd sends no telemetry, or usage data, and does not use a mailmd server. Store the archive in your normal computer backup or another location you control so a computer failure does not take out both your mailbox copy and its backup.

Search and use the files #

mailmd does not include its own search engine. Open the Markdown files in an editor or note app, search them with rg or grep, or filter index.jsonl with jq. You can also keep the archive in Git, a tool for tracking changes to files.

A coding agent such as Claude Code or Codex can search the archive when started in the mail folder. It reads the local files with its usual tools and sends the text it uses to the company that provides its AI model. Consider that data flow before asking an agent to inspect sensitive messages.

What mailmd does not do #

mailmd only reads email. It opens folders in read-only mode and requests permission to read messages. It never changes, moves, deletes, or sends them. It can connect several accounts, including Gmail, Outlook.com, iCloud, Fastmail, Yahoo, and mail hosted on your own server. Outlook.com connects through Microsoft Graph, which requires an OAuth app in Microsoft Entra.

The archive does not free Gmail storage by itself; you would need to delete messages from Gmail after confirming that the local copy is complete. mailmd also does not import messages back into a mailbox or convert them to PST or PDF. Use mailmd demo to create sample messages and inspect the format before connecting an account.