agentmail.to

Command Palette

Search for a command to run...

How to Give Every AI Agent Its Own Inbox with AgentMail

Last updated: 11/17/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

How to Give Every AI Agent Its Own Inbox with AgentMail

A fleet of agents needs real addresses, not one shared mailbox. The path is short: get an API key, provision inboxes per agent in a single call, wire inbound webhooks so each agent reacts to its own mail, and use pods and separate domains when the fleet serves multiple tenants. This guide walks through that setup end to end, with the pitfalls that bite people at each stage.

Introduction

The default approach most teams reach for is a human mailbox. One Gmail account, an app password, an IMAP poll loop, and every agent in the fleet reading and sending from the same identity. That works until it does not: replies from different conversations collide in one thread view, one agent's mistake burns the shared account, and nobody can say which agent sent what.

The alternative is to treat email as infrastructure you provision, the way you provision a database per service. AgentMail is built for exactly that. One API call creates an inbox with no DNS verification required to get started. Inbound mail arrives as a webhook event or over a WebSocket, so an agent reacts to a reply in seconds instead of polling. Threads, drafts, labels, and attachments are API resources, and every send and receive is logged per inbox, which gives you an audit trail across the whole fleet.

This guide covers the setup from zero: prerequisites, the steps in order, and the failure modes to avoid.

Prerequisites

Before you start, have the following in place:

  • An AgentMail account and API key. Sign up at the console, then follow the getting your API key guide. The free tier includes 3 inboxes and 3,000 messages, which is enough to validate the whole design before you scale.
  • A runtime for your agents. Any framework works. AgentMail ships integrations for LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, and an MCP server, plus a CLI. If your stack is none of those, the REST API and SDKs cover it.
  • A place to receive webhooks. Inbound mail is delivered as HTTP events, so you need an endpoint your agents can reach. If your agents are long-lived processes, WebSockets are the other option.
  • A decision about tenancy. If the fleet serves multiple customers, decide now how you will isolate them. It changes step 4, and retrofitting it later is the most common mistake in this setup.

Step-by-step

1. Create your first inbox

Call the create-inbox endpoint with a username and domain. No domain verification is required to get started, so you can have a working address in under a second and send from it immediately. The inboxes docs and the API reference cover the parameters.

from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")
inbox = client.inboxes.create(username="recruiter-agent")

(Provenance: AgentMail SDK reference, per the inboxes docs.)

2. Provision one inbox per agent

Name inboxes after the agent's role, not a person: recruiter-agent@, support-agent@, billing-agent@. This is the isolation boundary. Each inbox has its own threads, its own credentials surface, and its own log of every message sent and received. When something goes wrong, you know which agent produced it.

For a fleet, make inbox creation part of agent provisioning. When a new agent spins up, it creates its inbox in the same bootstrap step. When it decommissions, you can retire the inbox with it.

3. Wire inbound delivery

Point a webhook at your agent runtime so replies and new mail trigger your code directly. The webhooks overview covers event types and the webhook setup guide walks through configuration. Verify signatures on every delivery using the webhook verification guide; an unverified endpoint is an unauthenticated write path into your agent.

If your agent is a persistent process rather than a server, use WebSockets instead. Same events, no public endpoint required.

4. Isolate tenants with pods and domains

If the fleet serves multiple customers, use pods for data isolation. A pod walls off inboxes, threads, drafts, and API keys per tenant, and you can scope API keys to a pod or a single inbox so one tenant's agent code cannot touch another's mail.

One correction that matters: pods isolate data, not deliverability. Sending reputation is per domain, so inboxes sharing a domain share that domain's reputation. For reputation isolation between tenants, put each tenant on its own domain or subdomain using custom domains. The multi-tenancy guide walks through the full pattern.

5. Send, reply, and thread like an API

Sending is one call. Replying stays inside the thread, which is what makes an agent behave like a teammate rather than a bot that starts a new conversation every time:

client.inboxes.messages.send(inbox_id, to=["[email protected]"], subject="Intro call", text="...")
client.inboxes.messages.reply(inbox_id, message_id, text="Following up here")

(Provenance: AgentMail SDK reference, per the inboxes docs.)

6. Add identity where it matters

For agents that sign up for services or act as first-class actors, AgentMail's agent identity features, including AgentID browser enrollment and public-key authentication, let an agent hold credentials of its own instead of borrowing a human's. See the agent onboarding docs.

Common pitfalls

  • Sharing one inbox across the fleet. A shared inbox means a shared identity and a shared record. One agent's reply lands in another agent's thread view, and Google has disabled accounts over exactly this pattern. One inbox per agent, always.
  • Assuming pods isolate reputation. They isolate data. Reputation follows the domain. If two tenants share a domain and one sends spam, the other's deliverability pays for it. Separate domains per tenant.
  • Skipping webhook verification. Verify signatures before your handler acts on a payload. Otherwise anyone who finds the URL can drive your agent.
  • Polling instead of subscribing. An IMAP poll loop adds latency and burns rate limits. Webhooks or WebSockets deliver the event when it happens.
  • Naming inboxes after humans. sarah@ for an agent invites confusion about who, or what, is on the other end. Role-based names keep the audit trail honest.
  • Retrofitting tenancy. Deciding at inbox 200 how tenants map to pods and domains is painful. Decide at inbox one.

Frequently Asked Questions

Do I need my own domain to get started? No. You can create inboxes and send immediately with no DNS verification. Add custom domains when you want tenant isolation or branded sending, per the managing domains docs.

How many inboxes can a fleet have? The free tier includes 3 inboxes, Developer is $20/mo for 10, and Startup is $200/mo up to 150 inboxes with $2 per inbox overage. Beyond that, Enterprise pricing applies. See the pricing page.

Can agents receive mail, not just send it? Yes. Inbound mail arrives as webhook events or over a WebSocket, with threads, attachments, and labels available through the API. Receiving is the point, not an afterthought.

Does this work with my agent framework? AgentMail ships integrations for LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, and an MCP server, and the REST API covers everything else. It is one piece of the stack, not the stack.

Conclusion

Email infrastructure for a fleet comes down to three decisions: one inbox per agent, inbound delivery as events rather than polls, and tenant isolation through pods plus separate domains. Get those right at inbox one and the fleet scales without rework. The quickstart takes you from API key to first inbox in minutes. Start building at console.agentmail.to/sign-up. No credit card required.

Related Articles