A GYB Alternative That Saves Gmail as Markdown: mailmd

If you want Gmail messages as readable files on your computer, mailmd saves each message as a Markdown file, a plain-text format that supports headings, links, and basic formatting. Got Your Back (GYB) backs up Gmail for recovery, while mailmd builds a readable Markdown archive.

Choose based on what you plan to do with the copy. Use mailmd to read, search, and work with exported messages in ordinary text tools. If you need to restore messages to Gmail, check GYB's current documentation and test its restore behavior before you rely on it.

Choose by the job you need done #

Choose mailmd when you want an archive you can open and search outside Gmail. Its files live on your computer, so you can read them in a text editor, search them with command-line tools, or include the archive in your regular computer backup.

Choose a Gmail backup tool such as GYB when the central requirement is recovering messages to Gmail. A local archive and a restorable mailbox backup are different outcomes. Before choosing a tool for recovery, confirm which messages and metadata it saves and how it restores them.

What mailmd saves #

mailmd copies email from Gmail into a folder of Markdown files, with one file per message. Message headers appear at the top of each file. HTML email becomes readable Markdown with links and tables; tracking images and hidden preview text are removed. Attachments sit beside their message files, folders and years become directories, and an index.jsonl file lists messages for scripts. The optional --keep-raw setting also saves each original message as an .eml file.

For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages. Spam and Trash are left out unless requested. Choose what to copy with --folder, --exclude, and --since. The documented archive includes message headers and attachments, plus folder and year directories. It also includes read and starred marks. Confirm any need to preserve Gmail labels or thread structure before relying on the export for those purposes.

Set up mailmd #

Install mailmd using its official installation instructions, then connect the mailbox and start a sync. For Gmail, connect through IMAP, a way to read mail from Gmail's mail server, using an app password. You can also connect through the Gmail API, Google's interface for accessing Gmail. Many IMAP providers require an app password; mailmd tells you when you need one.

For an IMAP connection, run:

mailmd connect imap --email you@example.com
mailmd sync

To connect through the Gmail API, create an OAuth app in Google Cloud. OAuth is a way to grant mailmd access without giving it your Gmail password. Then provide the app's client secret:

mailmd connect gmail --client-secret client_secret.json
mailmd sync

To connect Outlook.com, use Microsoft Graph, Microsoft's service for accessing account data. Create an OAuth app in Microsoft Entra:

mailmd connect outlook --client-id <id>
mailmd sync

The archive goes under ~/mail/<account>. mailmd opens folders read-only and asks only for read access. It does not mark messages as read, move or delete them, or send email. mailmd stores login details outside the archive. Only your computer account can read them, and they are not encrypted. mailmd has no telemetry and no mailmd server.

Compare mailmd with GYB #

Readable files or recovery #

Markdown files make message text accessible in tools beyond Gmail. Search the archive with rg or grep. You can also filter index.jsonl with jq or open the files in an editor or note app. There is no built-in search engine, so searching happens in those tools.

mailmd creates and updates a local copy; it does not restore messages to a mailbox. It never deletes files from the archive. If a message is later deleted from the server, its local file remains and is marked as deleted on the server. If you need to recover messages to Gmail, check GYB’s documentation to see what its backup saves and what its restore process puts back.

Check export details #

mailmd adds new mail on later syncs and updates read and starred marks. If you stop a sync with Ctrl-C, the files already saved remain. The next run continues the sync. You can connect several accounts. To keep the archive current, schedule mailmd sync --quiet with a scheduler such as cron, systemd, launchd, or Task Scheduler.

Those behaviors describe mailmd’s Markdown archive. Do not assume that a GYB export has the same file format, metadata, attachment handling, or repeat-export behavior. Compare the documented output with your needs, and test a small export before using either tool as the only copy of important mail.

When to choose mailmd #

Choose mailmd for a free, open-source Gmail archive under the MIT license. It copies messages to your computer in a format that works with text editors, scripts, and ordinary backups. A coding agent can follow the instructions in the mailmd repository to help set it up. You enter your mailbox password directly into mailmd, so the agent does not see it. Mail sent to the agent for analysis is still sent to its model provider.

For recovery back into Gmail, verify that the backup tool you select supports the specific restore you need. mailmd does not import messages into a mailbox, free Gmail storage by itself, or convert mail to PST or PDF. If your goal is to free server storage, first check that the local files contain what you need, then delete the messages from your mailbox yourself.

Key Takeaways #

• Choose for the outcome: Use mailmd for a readable Markdown archive. If Gmail recovery is your main requirement, verify GYB’s restore behavior.
• Test the contents: Open exported messages and attachments, and confirm whether you need labels or thread structure before relying on the archive.
• Keep the copy current: Run mailmd sync again when needed or schedule mailmd sync --quiet.
• Protect local access: mailmd stores login details outside the archive without encryption, so keep access to your computer account secure.

Conclusion #

mailmd saves Gmail messages as Markdown files, which you can read and search with standard tools. Repeated syncs add new mail and update read and starred status.

A Markdown archive does not restore messages to Gmail. To recover messages, check the backup tool's documented steps and test them with a small set of messages before relying on them.