How to build an AI email assistant

Connecting your mail is the short part. What decides whether the assistant still works in month six is the structure it files into, and that is the part most builds skip.

The phrase covers two different products. One lives inside your mail client and helps you write faster: better autocomplete, a summary at the top of a long thread. The other reads your mail where it already sits, in the context of the projects and people it belongs to, and then does something with it. It files the invoice against the right project, logs the decision buried in paragraph four, and drafts the reply you owe. This page builds the second one, on Claude Code, on your own machine, in files you own.

The build itself is short enough to finish in a sitting. The reason people stall is not the connection. It is that a system that can read your mail and has nowhere to put anything is a chat window pointed at your inbox.

The connection is the short part

Connectors are configured once in the Claude app and, on current versions, carry across to Claude Code. Your mail provider is almost certainly in the directory, and the setup is a login and a permissions grant rather than anything technical. Both the labels and that cross-surface behavior move as Claude changes, so the assistant itself will point you to where they live in your version.

The choice worth thinking about is permissions. Grant read access, not send. Reading changes nothing in the mailbox, so a read-only connection is reversible while you learn what the system does with your mail, and you can widen it later once you trust what you are seeing. Even then, sending should stay behind your approval. An assistant that drafts and waits saves you time. One that sends costs you more supervision than the work would have taken.

If connectors are out of reach, because your plan does not offer them or a work administrator blocks them, a folder you forward decision-relevant mail into gets you most of the way with any provider, and the rest of the build works against it unchanged.

The structure it files into is the actual build

This is the real build, and it is where the difference between a demo and a system gets decided. Before the assistant reads a single thread, it needs three places to put what it finds: a record per project, a record per person, and a running log of decisions. Without them, every run produces a summary you read once and lose.

Keep them as plain text files in ordinary folders. Not a database, not an app. Files you can read without the tool that wrote them, which is the whole argument behind owning your notes rather than renting them, and the same structure a second brain built with AI runs on. A decision log is the one people leave out and miss first, because email is where decisions actually get made and then forgotten.

The instruction is where it lives or dies

You are not writing code. The assistant runs on an instruction you write in plain sentences, saved once and re-run on a schedule, and the wording of that instruction is most of what decides the quality of the result. A working one has to settle four things: what counts as new since the last run, how a thread gets matched to something already on file, what the categories are and what happens to each one, and what the assistant does when it is not confident. The book provides the prompts, written out and tested, for this step and every other one in the build.

However you word it, run it against ten real threads and read what it actually did. Where it routed something wrongly, the fault is almost never the model. It is either an instruction vaguer than you thought or a structure underneath too thin to route into. Fix whichever one is actually wrong and run it again. Ten threads will teach you more than a week of planning.

What you will hit, and it is not a bug

The loop works, and then a few weeks later it works less well. One project quietly becomes two records. A person gets filed twice under different spellings. Threads start landing in a general pile because nothing more specific fit.

That is not the assistant degrading. It is the structure underneath being asked to hold more than it was designed for, and email is only the first input. Meetings arrive next, then documents, and they all have to land in the same records or you get three parallel systems that disagree. That is why capturing notes automatically and automatic meeting notes belong to the same build rather than to separate ones, and why the promises buried in your sent mail need somewhere to be tracked before they go cold.

Connecting mail is twenty minutes. The structure it files into is what decides whether any of this still works in month six. If you want to see what the finished loop does before you build toward it, AI email triage describes the routing end of the same system.