An Open Source Email Archive on Your Own Disk: mailmd

If you want a copy of your email on your own computer, mailmd saves it as local files. This free, open-source command-line tool writes each message to its own Markdown file in a folder.

mailmd works with IMAP mailboxes. It connects to Gmail through the Gmail API and to Outlook.com and Microsoft-hosted mail through Microsoft Graph. You can search the files with standard tools, but you must protect the archive and back it up yourself.

What mailmd puts on disk #

mailmd turns mailbox messages into files arranged by account and mailbox folder, with a folder for each year. Each message file starts with its headers, such as sender and date, in a block called frontmatter. mailmd renders HTML email as readable Markdown, preserving links and tables. It drops tracking images and hidden preview text. Attachments sit next to their message files. An index.jsonl file lists the messages for use in scripts, and --keep-raw also saves each original message as an .eml file.

mailmd supports any IMAP mailbox, including Gmail, iCloud, Fastmail, Yahoo, and mail hosted on a personal server. Gmail can also connect through its API. Outlook.com and Microsoft-hosted mail use Microsoft Graph because most Outlook mailboxes no longer accept IMAP passwords. Those API connections require an OAuth app - a registration that lets mailmd request access to your mailbox - which you create in Google Cloud or Microsoft Entra.

The project is free and open source under the MIT license. mailmd reads mail without changing it: it opens folders read-only, requests read access, and does not mark messages as read, move or delete them, or send email. Each sync adds new messages and updates whether messages are read or starred. If you stop a sync with Ctrl-C, mailmd keeps what it saved so the next run can continue. It never removes files from the archive; if a message is later deleted from the server, its archived file stays and is marked as deleted on the server.

By default, mailmd leaves out spam and trash. For Gmail over IMAP, it syncs All Mail, which includes archived messages. Use --folder, --exclude, or --since to choose what to copy.

mailmd versus a hosted archive #

A hosted archive keeps messages on infrastructure managed by a provider. mailmd keeps its archive as files on a disk you control. You can open the files directly, but you must store, protect, and maintain them.

Control and access #

With mailmd, the archive remains available as local files even when you are not using a mail provider’s archive interface. You can open the files in an editor or note-taking app, search them with command-line tools, or use the index in scripts. A hosted archive offers access through its provider, which manages the service but also remains part of how you reach the stored messages.

Choose mailmd when direct control of the files matters and you are willing to manage them. Before relying on a hosted service, check its export and retention terms so you know how to retrieve messages and how long the service keeps them.

Upkeep and protection #

A local archive shifts responsibility to its owner. Disk failure can destroy the only copy, so keep the archive in a normal backup or another protected location, and consider disk encryption. mailmd can run on a schedule with mailmd sync --quiet using cron, systemd, launchd, or Task Scheduler, but scheduling syncs does not protect the files from hardware failure.

mailmd stores login information outside the archive. It does not encrypt those credentials, and only your user account can read them. There is no mailmd server and no telemetry. Protect the computer and its user account as well as the archived messages.

mailmd versus a mailbox backup #

An archive gives you readable copies of messages for reference and search. A backup is a protected copy intended to help recover data after loss. mailmd creates an archive, but it does not restore messages to a mailbox or replace a separate backup of the archive folder.

If a server message disappears after mailmd has copied it, the local file remains. That helps preserve a record, but it does not recreate the message in Gmail, Outlook, or another mailbox. mailmd also does not free mailbox storage by itself. To make room, delete messages from the mailbox only after confirming that the archive copy exists and deciding that the deletion is appropriate.

Treat the mailmd folder as data that needs its own backup. Keep a separate copy, and test that you can restore files from it before depending on the archive as your only record.

Set up and use mailmd #

Choose mailmd if you want individual, portable message files and are comfortable using a command line. It runs on Linux and macOS, and on Windows through Git Bash. To install it manually, connect a mailbox, and start a sync:

curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh
mailmd connect imap --email you@example.com
mailmd sync

The connection command depends on the mailbox. For Gmail over IMAP, use an app password if required by the provider. To connect Gmail through its API, use mailmd connect gmail --client-secret client_secret.json. For Outlook.com or Microsoft-hosted mail, use mailmd connect outlook --client-id <id> with an OAuth app you created. mailmd says when an IMAP provider requires an app password. The first sync saves mail under ~/mail/<account>. To try the tool without connecting a mailbox, mailmd demo writes sample messages.

Import and file formats #

mailmd accepts IMAP mailboxes and supports Gmail and Outlook through their respective APIs. The Markdown files keep message headers and readable body text, with attachments saved next to the messages. Add --keep-raw if you also want the original .eml files.

The files remain usable outside mailmd, which makes them easier to inspect or process with other tools. mailmd does not create PST or PDF files from messages or import mail back into a mailbox.

Search and export #

mailmd has no search engine of its own. Search the archive with rg or grep, open the files in an editor or note app, or filter index.jsonl with jq. You can search the files without relying on a mailmd search service, but you must choose and use your own tools.

For example, rg "invoice" ~/mail searches the archive files for the word “invoice.” Keep the archive folder in a Git repository or a regular backup if you want a separate copy. Git can track changes to files, but it should not be treated as a substitute for a backup.

Updates and recovery #

Run mailmd sync to bring in new mail and update whether messages are read or starred. To keep the archive current, schedule mailmd sync --quiet with the scheduler available on your computer. A scheduled sync updates the archive; a separate backup is still needed for recovery after a disk failure.

If you use a coding agent - an AI tool that reads and changes files - to set up mailmd, start it in the mail folder and ask it to follow the setup instructions in the project repository. The agent sends the file content it reads to its model provider. Type your mailbox password directly into mailmd so the agent does not see it. The same local archive still needs protection and backups.

Who should use mailmd #

mailmd suits people who want email stored as files on storage they control and value open-source software. They also need to be willing to set up and maintain the archive. It is particularly useful when messages need to remain readable and searchable outside a mail provider’s interface.

A managed archive is a better fit for someone who wants a provider to handle more of the infrastructure. mailmd requires the owner to protect the disk, arrange backups, choose search tools, and manage access. It is also a poor fit if the goal is to restore messages into a mailbox, convert them to PST or PDF, or free mailbox space automatically.

• Keep a local copy: mailmd stores each message as a Markdown file with headers, readable content, and nearby attachments.
• Protect the archive separately: mailmd does not delete archived files, but a disk failure can still destroy them; keep and test a separate backup.
• Choose the right connection: Use IMAP for supported mailboxes, Gmail’s API for an API connection, or Microsoft Graph for Outlook.com and Microsoft-hosted mail.
• Plan for search and upkeep: mailmd has no built-in search engine, so use tools such as rg or jq and schedule syncs if you want the archive updated regularly.
• Keep its limits in mind: mailmd does not restore mail to a mailbox, create PST or PDF versions of messages, or free mailbox storage by itself.

mailmd keeps email as portable files on a disk you control. It reads mail without changing it and keeps archived files after server-side deletion. You must use the command line, choose search tools, and back up the archive.

To set up the archive, connect the mailbox, run a sync, confirm the files are where you expect them, and make a separate backup.