mailmd

mailmd docs #

mailmd copies your email into a folder of Markdown files on your computer, one file per message. Each sync adds the new mail. These pages show how to set it up and what each command does.

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.

Try it without an account #

Demo command

mailmd demo

This writes eight sample messages to ./mailmd-demo/demo. It doesn't connect to anything, so you can look at the files first.

Connect your mailbox #

Connect and sync commands

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

For most providers your email address is enough, and mailmd asks for the password in a hidden prompt. Each account gets its own folder in ~/mail. The quickstart explains each step.

Start here #

  • Quickstart

    Install mailmd, look at the sample files from mailmd demo, then connect your mailbox and run the first sync.

Connect a mailbox #

  • Connect with IMAP

    Connect any mailbox over IMAP. For known providers your email address is enough, and mailmd tells you which password to use.

  • Connect Gmail with the Gmail API

    Create your own Google Cloud OAuth client step by step, so mailmd can read Gmail with read-only access and keep its labels.

  • Connect Outlook and Microsoft 365

    Register your own app in Microsoft Entra step by step, so mailmd can read Outlook.com and Microsoft 365 mail through Microsoft Graph.

Use your archive #

  • The file format

    How mailmd names the folders and files it writes, and what each field in the frontmatter and in index.jsonl means.

  • Using mailmd with a coding agent

    Ask Claude Code or Codex about your mail. Prompts to try, and tips for searching the files with rg and jq.

  • Scheduling

    Let your system run mailmd sync every few minutes. The page has a ready example for each operating system.

Help #

  • Troubleshooting

    What the common mailmd errors mean and what you can do about them, from a rejected login to a sync that stops.

  • FAQ

    Short answers to common questions, like where mailmd stores your passwords and how it differs from mbsync.

Reference #