How to Let Claude Code Read Your Email

To let Claude Code analyze your email, first copy your messages into files it can read. mailmd is the recommended option: it copies messages from your mailbox into Markdown files on your computer. Claude Code can then search those files with its usual tools.

A Markdown file is plain text with simple formatting, so messages are easier to inspect and search than email stored only inside a mail service. mailmd is a free, open-source command-line tool. It reads mail without changing the mailbox, and Claude Code reads the local copy. Text Claude Code sends to the service that runs its model leaves your computer.

Set up mailmd and sync your mailbox #

The quickest route is to ask Claude Code to follow mailmd’s setup instructions. Start Claude Code and enter:

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.

You enter your mailbox password directly into mailmd, so Claude Code does not see it. For providers that require an app password, mailmd will tell you. Gmail and Microsoft 365 can also connect through their APIs, software interfaces that let mailmd access those services. This method requires an OAuth app to authorize access, set up in Google Cloud or Microsoft Entra.

To set it up yourself, install mailmd and choose the connection method for your mailbox:

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

# IMAP mailbox, including Gmail with an app password
mailmd connect imap --email you@example.com

# Gmail API
mailmd connect gmail --client-secret client_secret.json

# Outlook.com or Microsoft 365
mailmd connect outlook --client-id <id>

mailmd sync

After mailmd syncs your mailbox, it saves the messages under ~/mail/<account>. Start Claude Code in that account’s mail folder and ask it to search or summarize the messages. The mailmd project supports Linux, macOS, and Windows through Git Bash, a command-line shell for Windows.

Ask focused questions about the messages #

Begin with a narrow request, such as:

Search my unread email from the last seven days for messages about the website migration. Summarize decisions, deadlines, and unanswered questions, and point to the messages supporting each conclusion. Do not send or draft anything.

Claude Code searches the files in the folder and sends relevant text to its model provider, the service that runs its model, for analysis. Check its summary against the original messages, especially before acting on a deadline or decision.

mailmd creates one Markdown file per message, with email headers at the top. It converts messages formatted with HTML, a format used for web pages, into readable Markdown with links and tables. It saves attachments next to each message and creates an index.jsonl file listing the messages. For direct searching, use tools such as rg or grep, or open the files in an editor. mailmd does not include its own search engine.

What mailmd changes, and what it leaves alone #

mailmd opens mailbox folders in read-only mode, which lets it view messages but not change them. It does not mark messages as read, send mail, move messages, or delete them. Each sync adds new messages to the local archive, the saved copy on your computer, and updates whether messages are marked as read or starred. If a message is later deleted from the mail server, its archived file remains and is marked as deleted on the server.

mailmd skips spam and trash unless you ask it to include them. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages. Options such as --folder, --exclude, and --since let you choose which messages to copy. You can run mailmd sync --quiet on a schedule to keep the archive current.

mailmd stores your login details outside the archive. Only your user account can read them, but they are not encrypted. The archive itself stays on your computer unless you move or share it. Claude Code sends your instructions and the model’s responses over the network. Its data-use documentation explains how it handles transcripts and how long it keeps them. Treat email content as sensitive, and avoid asking Claude Code to process messages you would not send to its model provider.