Your mailbox as Markdown files
A command-line tool that copies your email into files on your disk.
Install
$ curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh
Set it up with your coding agent
Set up mailmd so you can read my email. Use https://github.com/vincentsch/mailmd: read its AGENTS.md and follow the steps. Connect my mailbox and run the first sync. Then show me where the files are.
What does mailmd do with my mail?
- It only reads your mail
- IMAP folders are opened read-only, and the Gmail and Microsoft logins only ask for read access. mailmd never sends or deletes a message, and it doesn't mark mail as read.
- Your copy stays on your computer
-
There is no mailmd server and no account to sign up for. The mail
goes from your provider into
~/mail, or into a folder you choose. - The files are plain text
- Each message is a Markdown file with its headers at the top. Any editor opens it, and you can read it without mailmd.
Free and open source.
Install now
What can I do with the files?
The folders are the same as in your mailbox, with one more folder for each year. You can search and read the files with the tools you already have.
- Search
-
Search the files with rg or in your editor. Each file starts with
lines like
from:anddate:, so you can also search by sender.
- Read
- mailmd turns HTML mail into Markdown and keeps the links and tables. Hidden preview text and tracking images are left out.
- Attachments
- Attachments go into a folder next to the message. The message lists their names at the top and links to them at the end.
- Scripts
- The block at the top of each file is YAML, so any YAML library can read it. A script gets the sender and the date without parsing raw email.
How does a sync work?
You need two commands. mailmd connect saves a login, and
mailmd sync copies the new mail.
The quickstart
Can my coding agent read my mail?
Yes. Coding agents like Claude Code and Codex are good at reading folders of text files. Start the agent in your mail folder and ask it about your mail.
The agent needs no login.
It reads files that are already on your computer, so it needs no plugin and no password.
It can follow a thread.
Messages of one conversation share a thread_id. The
agent finds the other messages and reads them in order.
It can search the index.
Each account folder has an index.jsonl with one
line per message. The agent can filter it with jq before it
opens a message.
A Claude Code session over the sample mail from mailmd demo.
What can't mailmd do?
mailmd copies mail from your provider to your computer. It can't change anything in your mailbox.
- You can't send or reply with it
- mailmd is not a mail program. When you edit a file, nothing changes on the server.
- Outlook and the Gmail API need your own app
- Google and Microsoft only let a program read mail after someone registers it with them. You create a Google OAuth client or a Microsoft app registration once, and mailmd uses it. At work, an admin may have to approve the read access. For Gmail you can use IMAP with an app password instead.
- Gmail over IMAP comes as one folder
-
For a Gmail address over IMAP, mailmd syncs only
[Gmail]/All Mail. You get every message once, archived mail included, but no separate Inbox or Sent folder and no labels. The Gmail API keeps the labels. - Deleted mail stays in your folder
-
When a message is deleted on the server, mailmd keeps the file and
marks it with
deleted_on_server. Files you delete yourself can come back when mailmd reads a folder again from the start. - Attachments are copied as they are
- mailmd doesn't pull the text out of PDFs or Office files. A search over the Markdown files won't find words inside an attachment.
- Logins are saved in a plain file
- mailmd saves each login in its config folder, outside your mail. The file isn't encrypted. On Linux and macOS only your user can read it, and mailmd doesn't use the system keychain yet.
Questions and answers
Which mail providers does it work with?
Any mailbox with IMAP. For common providers like Gmail and Fastmail, your email address is enough. Outlook.com and most Microsoft 365 mailboxes no longer accept passwords over IMAP, so mailmd reads them through Microsoft Graph. Gmail also works through the Gmail API.
Can I try it before I connect my mailbox?
Yes. mailmd demo writes eight sample messages to
./mailmd-demo/demo and doesn't connect to anything. The
pictures on this page show those files.
Can I sync only some of my mail?
Yes. --folder and --exclude choose
folders, and --since 12m leaves out mail older than 12
months. Give these flags to mailmd connect to save them
for the account. Spam and trash are left out by default. With
--include Spam, a sync also copies the spam folder.
mailmd list folders shows which folders a sync copies.
Does mailmd send my mail anywhere?
No. It talks only to your mail provider, and to GitHub when you run
mailmd update --check. It has no telemetry. A coding
agent on a cloud model sends what it reads to its provider, like any
other file you show it.
Can I run it on a schedule?
Yes. Let your system run mailmd sync --quiet every few
minutes. Without an account name it syncs all your accounts, and a
run that finds nothing new doesn't touch your message files. The
docs have an example for each operating system.
Can I also keep the original email?
Yes, with --keep-raw. mailmd then saves each message it
fetches as an .eml file next to the Markdown file, as
the provider sent it. Messages that are already in the archive don't
get one.
What if a message doesn't convert well?
When the conversion loses most of the words, like with a newsletter
that is one big image, mailmd uses the plain text part. With
--prefer-text it always uses the text part when there
is one.
Does it work on Windows?
Yes. There are release binaries for Windows, and the install script works in Git Bash. So far mailmd has been used mostly on Linux, so please open an issue if something doesn't work.
Does it work with Obsidian?
Yes. Obsidian can open the mail folder as a vault, because the files are plain Markdown.
Is mailmd free?
Yes. It is open source under the MIT license, and there is no paid version.
How do I install mailmd?
curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh