agentmail.to

Command Palette

Search for a command to run...

How to Give AI Agents Their Own Email 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 AI Agents Their Own Email Inboxes with AgentMail

Transactional email APIs were built for one job: an application blasting mail at humans. They handle sending well and treat everything else, receiving, threading, identity, as someone else's problem. If your agent needs to own an address, read what lands in it, and reply in context, you can bolt that onto a send-only API, or you can start with an inbox primitive. This guide walks the second path: provisioning inboxes per agent with one API call, wiring inbound webhooks, threading replies, isolating tenants, and shipping a working agent email loop.

Introduction

An agent that can only send email is half an agent. It cannot receive a verification code, get CC'd on a thread, or act on a customer reply, because the address it sends from is a firehose, not a mailbox. Teams usually discover this after wiring a send-only API into their agent, then spending a sprint on IMAP polling, reply parsing, and a shared human inbox that everything collides in.

The failure modes are predictable. Agents impersonate a human's email account because that is the only credential available. Replies from different conversations land in one bucket with no threading context. Nobody can say what the agent sent last Tuesday, because there is no audit trail. Some teams respond by building custom SMTP infrastructure, which is months of engineering on a problem that should not exist.

AgentMail is the identity and email layer for AI agents: give any agent its own inbox, its own domain, and a full audit history of everything it sends and receives. This guide covers the implementation from API key to production webhook loop.

Prerequisites

Before you start, have the following ready:

  • An AgentMail account. Sign up at the console, no credit card required. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test the whole loop.
  • An API key. Follow the getting your API key guide and store it in your secret manager, not in code.
  • Python 3.10+ or Node 18+, depending on which SDK you prefer.
  • A running agent. AgentMail drops into any framework: LangChain, Google ADK, the OpenAI Agents SDK, the Claude Agent SDK, or your own loop. There is also an MCP server and a CLI if you want to drive email from a tool-calling agent without writing SDK code.
  • A public HTTPS endpoint for webhooks, if your agent should react to inbound mail in real time. For local development, WebSockets let you skip the tunnel entirely.

Step-by-step

1. Create your first inbox

One API call provisions an inbox. No DNS records, no domain verification, no waiting. The quickstart walks this in under five minutes.

from agentmail import AgentMail

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

Code per the AgentMail SDK reference, see the API reference.

The client class is AgentMail. Sending is client.inboxes.messages.send(inbox_id, ...), and reading a thread is client.inboxes.threads.get(...). Keep those three calls in mind; they are the whole surface for a basic agent.

2. Give each agent its own inbox

Provision one inbox per agent, not one shared inbox for the fleet. This is the isolation step. One inbox per agent keeps each agent's data, threads, and credentials separate, and gives you a clean audit trail per agent: every send and receive is logged against the inbox that did it.

If you serve multiple customers, go one level further with pods. Pods isolate inboxes, threads, drafts, and API keys per tenant, with pod- and inbox-scoped keys so one tenant's agent cannot touch another's mail. The multi-tenancy guide covers the setup.

3. Send your first message

client.inboxes.messages.send(
    inbox_id=inbox.inbox_id,
    to=["[email protected]"],
    subject="Weekly report",
    text="Here is what changed this week.",
)

Code per the AgentMail SDK reference, see the API reference.

Attachments, labels, drafts, and lists are all part of the same API surface, documented under messages.

4. Wire up inbound mail

This is the step a send-only API cannot do at all. When a reply lands, AgentMail fires a webhook to your endpoint, so the agent reacts in seconds instead of polling a mailbox. The webhooks overview covers setup, and webhook verification covers signing so you can trust the payload.

If you would rather not expose an endpoint, use WebSockets and receive inbound events over a persistent connection. That is usually the fastest path in development.

5. Reply in thread

When your agent responds, reply against the message ID so the answer lands in the same thread with full context, the way a teammate would:

client.inboxes.messages.reply(
    inbox_id=inbox.inbox_id,
    message_id=message_id,
    text="Got it, scheduling the follow-up.",
)

Code per the AgentMail SDK reference, see the API reference.

Thread context is what separates an agent that reads email from one that understands it. The threads docs show how to pull a full conversation history before the agent decides what to say.

6. Move to a custom domain for production

The default addresses are fine for development. For production, attach your own domain so mail comes from your brand. The custom domains guide and managing domains pages cover DNS setup. One thing to know early: sending reputation is per domain, not per inbox. If you run multiple tenants, give each tenant its own domain or subdomain rather than relying on inbox separation alone.

Common pitfalls

  • Sharing a human's inbox with an agent. Borrowing a person's email account means borrowing their identity, their history, and their credentials. Google has disabled accounts over exactly this pattern. One inbox per agent, always.
  • Polling instead of subscribing. IMAP polling adds latency and rate-limit risk. Webhooks or WebSockets give you the message the moment it arrives.
  • Treating reputation as per-inbox. Inboxes on the same domain share that domain's reputation. Plan domains per tenant, not just pods.
  • Skipping webhook verification. An unverified webhook endpoint will accept forged payloads. Verify signatures before your agent acts on inbound mail.
  • Ignoring rate limits until production. Check the rate limits page before your agent's first bulk run, and use idempotency keys on sends so retries do not double-send.
  • No audit trail. If you cannot reconstruct what an agent sent and why, you will regret it the first time a customer asks. Per-inbox logging is built in; do not build a parallel one.

Frequently Asked Questions

Why not just use a transactional email API for my agent? Because those APIs are built for an application sending mail to humans. Sending is table stakes; an agent also needs to receive, thread, and own an identity. Provisioning an inbox, getting inbound events, and replying in context are the core of AgentMail, not add-ons.

Do I need my own domain to get started? No. Inboxes are provisioned in a single API call with no DNS or domain verification required. Add a custom domain when you move to production and want mail from your brand.

How does multi-tenancy work? Pods isolate inboxes, threads, drafts, and API keys per tenant, with scoped keys and per-inbox webhook routing. For deliverability isolation between tenants, use separate domains or subdomains, since reputation is per domain.

What does it cost? The free tier includes 3 inboxes and 3,000 messages. Paid tiers start at $20/month for 10 inboxes, with higher tiers and custom Enterprise pricing above that. Current details are on the pricing page.

Conclusion

The decision in front of you is not which sending API has the best deliverability dashboard. It is whether your agent gets to be a first-class participant in email, with its own address, its own inbound events, and its own history, or a script that fires messages into a system it cannot read back from. The first path is a few API calls with AgentMail; the second is a custom SMTP project you will be maintaining for years.

Start with the free tier, provision one inbox per agent, wire the webhook, and you will have a working email loop this afternoon. Start building.

Related Articles