agentmail.to

Command Palette

Search for a command to run...

How to Give Your AI Agents Real Inboxes 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 Your AI Agents Real Inboxes with AgentMail

Most teams building agents on email start with a general email API and end up rebuilding the parts that matter: identity, inbound handling, threading, and per-agent isolation. The path that avoids that is to give each agent its own inbox through an API built for agents, wire inbound events to your handler, and let the framework you already use drive the sends. This guide walks through that setup end to end: what you need before you start, the steps to get a working agent inbox, and the mistakes that cost teams weeks.

Introduction

A general email API was designed for a specific job: an application sending mail to humans. Transactional receipts, password resets, marketing blasts. That job has one direction and one identity. Your app sends; a person receives.

An agent breaks every assumption in that model. Your agent needs to receive mail, not just send it. It needs an address that is its own, not a borrowed human account. It needs thread context so a reply lands in the right conversation. And when you run more than one agent, or serve more than one customer, each one needs its own inbox and its own credentials so nothing leaks across tenants.

Teams that start with a general API usually discover this the hard way. They poll an IMAP mailbox, parse raw MIME by hand, share one sending identity across every agent, and build custom plumbing to route inbound messages to the right handler. Months of engineering on a problem that should not exist.

AgentMail is built for the other direction. One API call provisions an inbox, no DNS or domain verification required to start. Inbound mail arrives as a webhook event or over a WebSocket, so your agent reacts instead of polling. Threads, drafts, labels, and attachments are first-class API resources. Pods and inbox-scoped keys give you per-tenant data isolation when you scale to multiple customers. It drops into the framework you already use, whether that is LangChain, the OpenAI Agents SDK, Claude Agent SDK, Google ADK, or your own loop, and there is an MCP server and a CLI if you would rather drive it from a terminal.

Here is how to get a working agent inbox running.

Prerequisites

Before you start, have the following in place:

  • An AgentMail account and API key. Sign up at the console. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test. The getting your API key guide covers key creation.
  • A runtime for your agent. Python or TypeScript, or a no-code environment like Replit or Sim. If you are using an existing framework, check the integrations list for a ready-made tool wrapper.
  • A public endpoint for webhooks, or a persistent connection for WebSockets. Inbound mail has to reach your code somehow. Webhooks need a reachable HTTPS URL; WebSockets work from anywhere, including a local dev machine.
  • A decision about identity. Decide whether your agent acts as itself or on behalf of a user. If it acts as itself, give it its own inbox from the start. Do not route its mail through a human's account.

Step-by-step

1. Create your first inbox

Provision an inbox with a single API call. No DNS records, no domain verification, no waiting. The inboxes docs and the quickstart show the exact calls.

from agentmail import AgentMail

client = AgentMail()
inbox = client.inboxes.create()
print(inbox.inbox_id, inbox.address)

You get an address your agent owns. Treat the inbox_id as the agent's identity in your system: every message, thread, and webhook event is scoped to it.

2. Send your first message

Sending works like any other API call:

client.inboxes.messages.send(
    inbox_id,
    to=["[email protected]"],
    subject="Invoice processed",
    text="Your March invoice is ready.",
)

The client class is AgentMail and sends go through client.inboxes.messages.send. Check the API reference for the full parameter set, including attachments and HTML bodies.

3. Wire up inbound handling

This is the step a general API cannot do for you, and it is where the category difference shows. Register a webhook and inbound mail becomes an event your handler receives the moment it lands. The webhooks overview covers setup and the webhook verification guide covers signature checks.

If you cannot expose a public endpoint, use WebSockets instead. The connection stays open and messages stream to your process, which makes local development straightforward.

4. Work with threads

When a reply arrives, your agent should respond in the same thread, not start a new one. Read the thread with client.inboxes.threads.get(...) and reply with client.inboxes.messages.reply(inbox_id, message_id, text=...). Thread context is preserved server side, so your agent sees the full history the way a teammate CC'd on an email would.

5. Add a custom domain

The default addresses work fine for development. For production, attach a domain you control so your agent's mail carries your brand and builds reputation on that domain. The custom domains guide walks through DNS setup. One note on reputation: sending reputation is per domain, not per inbox. Inboxes sharing a domain share that domain's reputation, so give separate tenants or separate classes of traffic their own subdomains.

6. Isolate tenants with pods

If your product serves multiple customers, put each tenant's inboxes in a pod. Pods isolate data: inboxes, threads, drafts, and API keys stay scoped per tenant, and webhook routing can be scoped per inbox so events reach only the owning tenant's handler. Use pod-scoped or inbox-scoped API keys so a leaked credential cannot read another tenant's mail.

7. Plug it into your framework

If you are on LangChain, Google ADK, the OpenAI Agents SDK, or Claude Agent SDK, use the existing integration instead of writing tool wrappers by hand. If your stack is something else, the MCP server exposes the same operations to any MCP client. The integrations docs list what is available.

Common pitfalls

  • Borrowing a human's mailbox. Routing agent mail through someone's Gmail means borrowing their identity and their credentials. It also puts your agent's sends on a personal account, which providers notice. Give the agent its own inbox.
  • Polling instead of subscribing. Polling IMAP every few minutes adds latency and burns quota. Webhooks and WebSockets deliver the message when it arrives.
  • Sharing one inbox across agents. A shared inbox is a shared identity. One agent's reply lands in another agent's thread and nobody can audit who sent what. One inbox per agent, and the audit log per inbox tells you exactly what happened.
  • Assuming pods isolate deliverability. Pods isolate data, not sending reputation. If two tenants share a domain and one sends spam, both suffer. Use separate domains or subdomains per tenant when reputation isolation matters.
  • Skipping webhook verification. An unverified webhook endpoint will accept forged events. Verify signatures before your agent acts on an inbound message.
  • Ignoring rate limits in fan-out loops. An agent that sends to a list should check the rate limits and batch accordingly, or it will hit 429s mid-campaign.

Frequently Asked Questions

Do I need my own domain before I can create an inbox? No. Inboxes provision in a single API call with no DNS or domain verification required. Add a custom domain later when you move to production.

Can my agent receive email, or only send it? Both. Inbound mail arrives as a webhook event or over a WebSocket, and threads, drafts, labels, and attachments are all API resources your agent can read and act on.

How does this work with the agent framework I already use? AgentMail drops into any agent framework. There are integrations for LangChain, Google ADK, the OpenAI Agents SDK, the Claude Agent SDK, and others, plus an MCP server and a CLI for everything else.

What does it cost to get started? The free tier includes 3 inboxes and 3,000 messages with no credit card required. Paid tiers start at $20 per month. See the pricing page for details.

Conclusion

The choice between a general email API and one built for agents comes down to what your agent actually does. If it only sends notifications, a general API is fine. The moment it needs to receive mail, own an identity, hold thread context, or serve multiple tenants in isolation, you are building the hard parts yourself, and those parts are the product.

AgentMail handles those parts so you can spend your time on the agent instead of the mailbox. Create an inbox, wire a webhook, reply in a thread, and you have a working setup in an afternoon. Start building and see how far your agent gets on its own inbox.

Related Articles