How to Convert Email to Markdown

When you save email messages as files you can search, edit, or use with scripts, Markdown gives you a readable format: plain text with simple markers for headings, links, and other structure. Email messages can contain formatted HTML, headers, and attachments, so you need to choose what to keep and how to organize it.

To convert a mailbox, mailmd is the recommended tool. It copies messages to a folder on your computer, with one Markdown file per message, and leaves the mailbox unchanged. It works with services such as Gmail, Outlook, and iCloud. The steps below show how to connect an account, sync messages, and find the files.

What the Markdown files contain #

Email headers contain information such as the sender, recipient, date, and subject. A message can also have a plain-text body, a formatted HTML body, and attached files. mailmd saves each message’s headers in frontmatter, a block of metadata at the start of a Markdown file. It converts HTML email into readable Markdown, keeping links and tables while removing tracking images and hidden preview text.

mailmd saves attachments beside each message file. It organizes folders and years into directories, and writes an index.jsonl file that lists messages for scripts. To keep a copy of each original email file too, run mailmd sync --keep-raw; mailmd then saves the original .eml file alongside the Markdown archive. An .eml file is a common format for storing one email with its headers and content.

If you have a single .eml file and cannot connect to its mailbox, mailmd’s mailbox-sync approach may not suit your task. A separate command-line converter, eml2md, converts .eml files. mailmd connects to a mailbox and syncs it over time while creating the Markdown archive.

Convert a mailbox with mailmd #

mailmd is a free, open-source command-line tool under the MIT license, and you run it from a terminal. It supports IMAP mailboxes, connects to Gmail through the Gmail API, and connects to Outlook.com through Microsoft Graph. IMAP is a standard that lets a mail client access messages on a mail server. The Gmail API and Microsoft Graph connections require an OAuth app, an account-access configuration you create in Google Cloud or Microsoft Entra.

Install mailmd, connect the account using the option for its provider, and start the sync:

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

# Choose one connection command:
mailmd connect imap --email you@example.com
mailmd connect gmail --client-secret client_secret.json
mailmd connect outlook --client-id YOUR_CLIENT_ID

mailmd sync

For an IMAP mailbox, including Gmail when you use an app password, use the IMAP command. Some IMAP providers require an app password; mailmd indicates when you need one. Use the Gmail API command with your OAuth client secret, or the Outlook command with your Microsoft Entra client ID. Most Outlook mailboxes no longer accept IMAP passwords, so mailmd connects to Outlook.com through Microsoft Graph.

mailmd asks only for permission to read messages and opens folders in read-only mode. It does not mark messages as read, move or delete them, or send email. The first sync saves the archive under ~/mail/<account>. Later syncs add new messages and update read and starred marks. If you stop a sync with Ctrl-C, mailmd keeps the files it has saved and continues on the next run.

Choose folders and keep the archive current #

mailmd skips spam and trash unless you ask it to include them. For Gmail over IMAP, it syncs All Mail, which includes archived messages. Use --folder, --exclude, and --since to choose which messages to copy. Check the mailmd project instructions for the available options.

mailmd never deletes files from the archive. If you delete a message from the mail server, its file stays in the archive and mailmd marks it as deleted on the server. This keeps the local copy, but the archive can include messages that are no longer in the mailbox.

To keep the archive up to date, use a scheduler such as cron, systemd, launchd, or Task Scheduler to run mailmd sync --quiet. Before relying on the archive, open a few message files and confirm that mailmd copied the folders and content you care about.

Search the Markdown archive #

mailmd has no built-in search engine. You can open the files in a text editor or note-taking app, search them with rg or grep, or filter index.jsonl with jq. You can also store the archive in Git or include it in a regular computer backup.

Treat the archive as sensitive because it contains local copies of email and attachments. mailmd does not run a server or collect telemetry, and it stores login information outside the archive. Those credentials are not encrypted, but only your user account can read them. If you ask a coding agent to search the archive, it sends the content it reads to its model provider. Consider this data flow before giving an agent access to confidential messages.