Email for AI Agents: The Definitive Guide

Email is the one channel every counterparty already has and the default identity primitive on the internet, which makes it the substrate AI agents fall back to for real work. An agent inbox is a provisioned object with an address the agent owns, a stored message history, automatic threading, a reachable identity, and a place in a tenant's isolation model. Sending is one method on it.

This guide covers what an agent inbox is, the reference architecture around it, how to operate one, how to run a fleet without a shared-reputation blast radius, and how to decide what your agent actually needs. If you're wiring email into an agent, you'll make a handful of decisions in the first hour that are hard to walk back: send-first API or inbox, one shared address or one per agent, default domain or your own, how you isolate tenants once there's more than one. Here's how to make each of those on purpose.

In this guide: What an agent inbox is · The reference architecture · Operating an inbox · Running a fleet with isolation that holds · Deliverability for a non-human sender · The decision framework · Where to go deep.

What is an agent inbox?

The most expensive early mistake is treating email for an agent as a send call. A send-first API moves a message and forgets it; inbound, if you want it, arrives as a raw webhook event you catch and store yourself. An agent inbox is a first-class object: an address the agent owns, a durable store, automatic threading, a reachable identity, and a resource that lives inside a tenant's isolation boundary. Sending is one method on it. The category distinction is unpacked in Email API vs Inbox API; here it's the foundation everything else sits on.

What is the reference architecture for agent email?

Four pieces, and where each responsibility lives.

Your app is the control plane. It provisions an inbox for each agent, holds your business logic, and decides what the agent does with what arrives. It never has to store or thread raw mail, because that isn't its job anymore.

The inbox is the agent's surface. It has an address, it sends, and it receives, and crucially, inbound is already stored and threaded when it lands, so the agent reads a conversation rather than a pile of disconnected events.

The webhook is the nerve. Rather than polling, your app subscribes to events (a message arrived, a thread updated) and reacts: hand the new message to the agent, trigger the next step, update your own records. The webhook tells you that something happened; the inbox API is where you read what happened.

The isolation layer is the container. A pod holds one tenant's inboxes, threads, drafts, and domains and keeps them separate from every other tenant's, and a custom domain carries that tenant's sending reputation. This is the part that turns a working prototype into something you can run for a hundred customers, and it's covered in its own section below.

Read as a loop: your app provisions an inbox, the agent sends from it, replies and codes come back already threaded, a webhook wakes your app, the agent acts, and the whole exchange stays inside one tenant's boundary.

How do you operate an agent inbox?

Provisioning is a single call, and the mechanics are worth getting exactly right because two details bite later if you don't.

from agentmail import AgentMail
from agentmail.inboxes.types import CreateInboxRequest

client = AgentMail(api_key="your_api_key")

# Provisioning: pass options through CreateInboxRequest
inbox = client.inboxes.create(
    request=CreateInboxRequest(client_id="research-agent-v1"),
)

# Sending: inbox_id is a kwarg; `to` accepts a string or a list
client.inboxes.messages.send(
    inbox_id=inbox.inbox_id,
    to="vendor@example.com",
    subject="Quote request",
    text="...",
)

# Reading inbound: .list() returns message metadata;
# fetch full bodies with .get() when you need them.
response = client.inboxes.messages.list(inbox_id=inbox.inbox_id)
for item in response.messages:
    msg = client.inboxes.messages.get(
        inbox_id=item.inbox_id,
        message_id=item.message_id,
    )
    content = msg.extracted_text or msg.text

First, client_id is an idempotency key. Send the same value twice (say your provisioning job retries after a network blip) and you get the same inbox back instead of a duplicate. That makes inbox creation safe to call from code that might run more than once, which in an agent system it will. Use a stable, meaningful value per agent so retries are automatically deduplicated.

Second, inbound is state you read back. messages.list() returns metadata for what the inbox already received and threaded; call messages.get() on any item to read the full body, using extracted_text when you want the reply content without quoted history. You don't reconstruct conversations or maintain a store. Pair the API reads with a webhook subscription so your app is notified the instant a reply or verification code lands.

The rest of the surface (labels as lightweight workflow state, drafts for human-in-the-loop approval, attachments, allow and block lists) is the operational detail a real deployment leans on. The full mechanics live in the build guide; this page tells you which of them you'll reach for.

How do you run a fleet of agent inboxes with proper isolation?

For one agent you can get away with almost any shape. For fifty or five thousand across many customers, isolation stops being a nicety and becomes the architecture. It's the place descriptions most often get wrong, so here it is precisely.

Data and context are isolated by pods. A pod contains one tenant's inboxes, threads, drafts, and domains, fully separated from other pods, and API keys are pod-scoped, so a key scoped to Acme's pod can touch Acme's resources and nothing else. Because the pod holds the agent's whole working surface, there's no shared space for one tenant's context to reach another tenant's agent.

Reputation is isolated by domains, not by pods. Mailbox providers score sending reputation at the domain level, and deliverability follows from it. Pods don't isolate reputation and were never meant to. You get reputation isolation by giving each tenant its own custom domain, scoped to that tenant's pod, so a spam complaint against one tenant lands on one tenant's domain and no one else's. Tenants sending on the shared default domain share its reputation, which is why per-tenant custom domains are the recommendation for anyone whose deliverability you contractually care about.

A related move worth knowing is subdomain segmentation by risk profile: send transactional mail from billing.company.com, cold outreach from outreach.company.com, and support from support.company.com, so a risky outbound motion can't drag down mail that has to arrive. The full strategy is in the domains guide.

How does deliverability work for a non-human sender?

Deliverability for an agent obeys the same rules as for anyone else. It comes down to authentication (SPF, DKIM, DMARC) and the reputation of the sending domain. There's no magic setting that makes an agent's mail land, only authentication done correctly and a domain whose reputation you protect. What changes at agent scale is that you want the ability to separate reputation per tenant and per risk profile (the custom-domain and subdomain moves above), so one bad sender can't set the tone for everyone.

Which architecture should you choose?

Most of this guide comes down to one table. Find the row that matches your case, and the architecture follows.

If more than one row matches, take the more capable option. The cost of an inbox you didn't need is small next to discovering mid-deployment that a reply had nowhere to land.

Where to go deep

This guide is the hub. Each question below has a dedicated deep dive that links back here.

Email API vs Inbox API for the category distinction, Can an AI Agent Have Its Own Email Address? for identity, and Multi-Tenant Email with Pods for the isolation model in depth. For the full mechanics of every operation covered above, the 21-chapter build guide is the reference.