How to Get Your Email into Obsidian

To read email in Obsidian, save messages as Markdown files, plain-text files with simple formatting, inside an Obsidian vault, the folder Obsidian uses for notes. Obsidian works with local Markdown files, so email saved in that format can be searched and linked like other notes.

mailmd is a free, open-source command-line tool that copies messages from an email account into Markdown files on your computer, one file per message. To keep an email archive in Obsidian, mailmd copies messages while leaving the original mailbox unchanged.

Set up mailmd and open the archive in Obsidian #

Install mailmd from a terminal on Linux, macOS, or Windows in Git Bash:

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

Then connect the account and sync its messages. The right connection command depends on the email service:

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

That connection works for mailboxes that use IMAP, a standard for accessing email, including Gmail with an app password. An app password is a separate passcode for an email program; many providers require one instead of the account’s usual password. Gmail users can also connect through the Gmail API. This requires an OAuth app, a Google Cloud setup that lets mailmd request access to the account:

mailmd connect gmail --client-secret client_secret.json

For Outlook.com and other supported Microsoft accounts, mailmd uses Microsoft Graph, Microsoft's service for accessing account data, and an OAuth app created in Microsoft Entra:

mailmd connect outlook --client-id <id>

The resulting files go to ~/mail/<account>. Open ~/mail as an Obsidian vault to see the account folder and its messages. A vault is a folder Obsidian opens and indexes. For background on Obsidian’s local-file approach, see its import documentation.

What appears in the vault #

Each message becomes a Markdown note. At the top, a block called frontmatter lists email headers, or message details, such as sender, subject, and date. HTML email is converted into readable Markdown with links and tables. mailmd removes tracking images and hidden preview text. Attachments are saved beside the message, while folders and years become directories. An index.jsonl file lists the messages for use with scripts. Add --keep-raw to also save each original .eml file.

By default, mailmd leaves out spam and trash. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages. Use --folder, --exclude, or --since to narrow what it copies. Run mailmd sync again to add new messages and update whether archived messages are marked as read or starred. The archive does not delete files: if a message is later deleted from the server, its file remains and is marked as deleted on the server.

Read-only access and local security #

mailmd opens mailbox folders in read-only mode, so it can read messages but not change them, and asks for permission to read them when you log in. It does not mark messages as read, move or delete them, or send email. If a sync stops, the files already saved remain; the next run continues.

Login details are stored outside the archive. They are not encrypted, but only your user account on the computer can read them. Keep that in mind when deciding which account to connect and how to protect the computer. There is no mailmd server or telemetry. If a coding agent handles setup, mailmd prompts you to enter your password directly, so the agent does not see it. However, if an agent reads the archived messages, it sends their contents to the provider of the AI model it uses.

Keep the archive current #

You can run mailmd sync --quiet on a schedule using cron, systemd, launchd, or Task Scheduler. As the archive grows, Obsidian indexes new Markdown files in the vault.

mailmd does not include its own search engine. Search the files in Obsidian or another editor, or use the terminal search tools rg or grep. To filter index.jsonl, use jq, a command-line tool for working with JSON data. The archive can also be kept in Git or included in a normal computer backup. mailmd does not free space in the email account; delete messages from the mailbox yourself only after confirming that the local copy and any needed attachments are present.

For more setup details, see the mailmd project. Its demo command writes sample messages without connecting to a mailbox.