How to Search Years of Email with an AI Agent

Finding an old quote, promise, or decision in years of email takes more than asking an AI to “remember” your inbox. The agent needs access to the relevant messages, and you need to check its answer against those messages.

A practical option is mailmd, a free, open-source command-line tool that copies email into Markdown files on your computer. A coding agent, an AI tool that can run commands on your computer, such as Claude Code or Codex, can search those files with its usual tools and summarize what it finds. The agent does not automatically review every message, so narrow searches and original-message checks still matter.

Make your email archive searchable #

An AI agent uses a language model, software trained to understand and generate text, to interpret a request and produce a response. To answer questions about email, it also needs a way to find and open messages. In this setup, mailmd creates the local archive, and the coding agent searches that archive.

Each message becomes a Markdown file, a text format that people and software can read. Message headers, such as the sender and subject, appear at the top. Attachments sit beside the message, and folders are arranged by year. HTML email is converted into readable Markdown. The index.jsonl file lists messages for use with scripts.

mailmd has no built-in search engine. Search the files with tools such as rg or grep, or use jq, a command-line tool for working with JSON data, to filter the index. An AI agent can use those same tools to find likely matches, inspect the messages, and explain how they relate. For example, ask it to find when a supplier changed a delivery date, then show the messages supporting each date.

Set up mailmd #

Install mailmd from a terminal:

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

Then connect the mailbox and sync it. The connection command depends on the provider:

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

That example applies to IMAP mailboxes, including Gmail with an app password. Some providers require an app password, and mailmd says when. For Gmail, connect through the Gmail API, which lets software access Gmail. This requires an OAuth app, a set of credentials that lets mailmd request access, created in Google Cloud:

mailmd connect gmail --client-secret client_secret.json

For Outlook.com or Microsoft 365, connect through Microsoft Graph, Microsoft's way for software to access these services, with an OAuth app created in Microsoft Entra:

mailmd connect outlook --client-id YOUR_CLIENT_ID

The Gmail and Microsoft API options require your own OAuth app. The archive is saved under ~/mail/<account>. For a first setup with a coding agent, start it in the folder where you want to work and use this prompt:

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 type your password into mailmd, so the agent does not see it. mailmd opens folders in read-only mode, so it can view messages but cannot change them. It requests read access and never marks, moves, deletes, or sends mail. It includes archived Gmail mail through All Mail; spam and trash are excluded unless requested. Use --folder, --exclude, or --since to choose what to copy. The mailmd project documentation describes its setup and options.

Ask focused questions and check the messages #

Start with a bounded request that names the people or organization and gives an approximate date range. Also say what evidence you want. For example:

Search the archive for messages about the supplier’s delivery date during the period I want to investigate. List the date, sender, subject, and what each message says about the delivery date. Separate proposals from accepted changes, and show the file path for each message.

Then check the cited files. An earlier email may contain a proposal that a later message changes; a quoted message may repeat old wording without confirming it. Ask the agent to search each year separately when the archive is large, and have it report which files it inspected. OpenAI also warns that broad Outlook searches can return incomplete results and recommends dividing large requests into smaller date ranges in its Outlook email guidance.

A missing result does not prove that a message never existed. Confirm that mailmd copied the right account and folders, and check whether older mail remains only in a separate archive. Run mailmd sync again to add new messages and update read and starred marks. A scheduled mailmd sync --quiet keeps the local copy current.

Keep mailbox access and AI use in mind #

mailmd does not send email or change the mailbox, but a coding agent sends the content it reads to the company that provides its AI model. Login details are stored outside the archive, are not encrypted, and can be read only from your user account. mailmd reports no telemetry and runs without a mailmd server.

Keep the archive in a location with appropriate access controls, and avoid asking an agent to inspect sensitive messages unless the model provider’s data practices suit your needs. The local copy also does not free mailbox storage by itself; deleting messages from the mail service is a separate action.