An OfflineIMAP Alternative That Writes Markdown: mailmd

If you want a local copy of your email as text files, mailmd is a better fit than OfflineIMAP. OfflineIMAP syncs mail between an IMAP server, which stores email for mail clients, and local mail storage. mailmd copies messages into Markdown files, a plain-text format that keeps text and links readable.

Choose based on how you plan to use the copy. A local mail store works with compatible mail clients and tools. Markdown files suit an archive you can open in any editor, search from the command line, or include in a regular backup.

How OfflineIMAP and mailmd store email #

OfflineIMAP keeps a local mail store synchronized with an IMAP mailbox. Mail clients and other compatible tools can then work with that local copy. If your goal is to store messages as Markdown, check whether your OfflineIMAP setup includes a separate export step.

mailmd connects to a mailbox and writes one Markdown file per message. Each file starts with frontmatter, a metadata block containing message headers. It turns HTML email into readable Markdown and saves attachments beside the message. It sorts files into directories by mail folder and year. An index.jsonl file lists messages for scripts to process.

Mail storage or Markdown files #

The two tools produce different kinds of local copies. With OfflineIMAP, messages remain in a mail store intended for mail-focused tools. With mailmd, messages become individual files that work with ordinary text editors and note apps.

For example, a reader who wants to open archived messages in a compatible mail client should favor a local mail store. Someone who wants to search email alongside other text files should favor Markdown. mailmd has no built-in search engine, but you can search its files with rg or grep, or filter index.jsonl with jq.

Sync and archive differences #

OfflineIMAP fits a workflow centered on keeping a local mail store in sync and using it with compatible mail clients. Its output serves that purpose; readers who specifically want Markdown need to account for a separate conversion or export step.

mailmd fits a text-based archive. HTML messages become readable Markdown with links and tables, while tracking images and hidden preview text are dropped. Headers appear in frontmatter, and attachments sit beside their message files. Use --keep-raw to save the original .eml message as well.

Sync behavior and server changes #

mailmd adds new messages each time it syncs and updates read and starred marks. It opens mail folders read-only and requests read access. It does not mark messages as read, move or delete them, or send mail. If a message is later deleted from the server, mailmd keeps its archive file and marks the file to show that the message was deleted from the server. Spam and trash are left out unless requested; for Gmail over IMAP, mailmd syncs All Mail, including archived messages.

You can control what mailmd copies with --folder, --exclude, and --since. If a sync is interrupted with Ctrl-C, mailmd keeps the files it already saved and continues on the next run. For ongoing copies, schedule mailmd sync --quiet with a tool such as cron, systemd, launchd, or Task Scheduler.

What each local copy requires #

A local mail store is useful when the next step is reading messages with a compatible mail client. Markdown files are useful when the next step is reading or searching them as text. mailmd does not import messages back into a mailbox, convert them to PST or PDF, or free up space in your mailbox. To free storage, first confirm the local copy, then delete the messages from the mailbox yourself.

mailmd is free and open source under the MIT license. Its login details are stored outside the archive. Only your user account can read them, and they are not encrypted. It sends no telemetry and uses no mailmd server. A coding agent, an AI tool that can read files, sends the text it reads to the company that provides its AI model.

Choose by your email workflow #

Choose OfflineIMAP when you need a local mail store for compatible mail clients or tools. Choose mailmd when your priority is readable Markdown files and text-based search. If you need both outputs, keep them as separate local copies: OfflineIMAP maintains the mail store, while mailmd connects to the mailbox and writes the Markdown archive.

Set up mailmd #

Install mailmd and connect it to the mailbox you want to copy. Run these commands in a terminal:

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

Choose a connection command based on the mailbox:

mailmd connect imap --email you@example.com
mailmd connect gmail --client-secret client_secret.json
mailmd connect outlook --client-id <id>

Use the IMAP option for IMAP mailboxes, including Gmail with an app password. The Gmail API option requires you to register an OAuth app in Google Cloud. This registration lets mailmd request access to the mailbox. Outlook.com and Microsoft mailboxes use Microsoft Graph and require an OAuth app in Microsoft Entra. Many IMAP providers require an app password; mailmd indicates when one is needed. You enter your password into mailmd yourself, so a coding agent following the setup does not see it.

Then copy the messages:

mailmd sync

The archive goes in ~/mail/<account>. You can also use mailmd’s documented setup prompt in a coding agent, then ask it to show where the files are. For a preview without connecting a mailbox, mailmd demo writes sample messages.

OfflineIMAP and mailmd at a glance #

• Choose by output: OfflineIMAP maintains a local mail store for compatible mail clients; mailmd writes individual Markdown files for text-based reading and searching.
• Use mailmd for Markdown archives: It saves headers, readable message content, attachments, and an index file, with an option to keep original .eml files.
• Keep server and archive changes separate: mailmd reads mail without changing it, and it keeps archived files even after messages are deleted from the server.
• Plan for access and search: Connect through IMAP or the appropriate provider API, then use an editor, rg, grep, or jq to search the archive.

Conclusion #

OfflineIMAP keeps a local copy of your mail in sync with the server. To build a readable email archive of Markdown files, connect your mailbox with mailmd, run mailmd sync, and then work with the files using the text tools you already have.