agentmail.to

Command Palette

Search for a command to run...

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

General-purpose transactional email APIs were built for one job: an application sending mail to humans. They are a poor fit when the sender is an agent that also needs to receive, read threads, and act on what lands. This guide walks through wiring an agent up with its own inbox using AgentMail: getting an API key, provisioning inboxes in code, sending, receiving through webhooks, replying in thread, and isolating tenants when you scale past one agent.

Introduction

An agent that can only send email is half an agent. The interesting work happens on the inbound side: a reply lands, a webhook fires, the agent reads the thread and decides what to do next. That requires a real inbox with real identity, not an SMTP relay bolted onto a shared mailbox.

The usual workaround is borrowing a human's account. That means borrowing that human's identity, sharing credentials, and mixing the agent's mail with everyone else's. Google has disabled accounts over exactly this pattern. The alternative is 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. One API call provisions an inbox with no DNS verification required. Inbound mail arrives as webhook events or over WebSockets. Threads, drafts, labels, and semantic search are API resources your agent can call like any other tool. It drops into any framework: LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, or plain Python.

The rest of this guide is the shortest path from zero to a working agent inbox. Each step maps to a page in the documentation, so you can go deeper on any part without guessing at the API shape. The whole setup is an afternoon if you already have an agent loop, and the code samples below are the actual SDK calls, not pseudocode.

Prerequisites

  • An AgentMail account. Sign up at the console, no credit card required.
  • An API key. Follow the getting your API key guide.
  • Python 3.9+ and the agentmail SDK, installed with pip install agentmail.
  • A webhook receiver if your agent should react to inbound mail. Any HTTP endpoint works. See the webhook setup guide.
  • Optional: a custom domain for production sending. The managing domains guide covers DNS setup.

Step-by-step

1. Create a client and provision an inbox

One call creates an inbox. No domain verification, no DNS records, no waiting on a deliverability review to get started.

from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")

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

Provenance: AgentMail Python SDK, per the API reference.

2. Send your first message

Sending is a method on the inbox. Attachments, custom headers, and scheduled sends are all supported by the same API.

client.inboxes.messages.send(
    inbox.inbox_id,
    to=["[email protected]"],
    subject="Hello from your agent",
    text="This message was sent by code, not by a human.",
)

Provenance: AgentMail Python SDK, per the API reference.

3. Receive inbound mail as events

Register your webhook URL and every message that lands in the inbox triggers an event your agent can act on. No polling. If you prefer a persistent connection, AgentMail also supports WebSockets for streaming inbound mail. Verify webhook signatures so your handler only trusts real events, per the webhook verification guide.

4. Read threads and reply in context

An agent CC'd on a thread can read the whole history and reply in line, like a teammate would.

thread = client.inboxes.threads.get(inbox.inbox_id, thread_id)

client.inboxes.messages.reply(
    inbox.inbox_id,
    thread.latest_message_id,
    text="Here is the summary you asked for.",
)

Provenance: AgentMail Python SDK, per the API reference.

5. Isolate tenants as you scale

When multiple customers or agents share one deployment, use pods to wall off each tenant's inboxes, threads, drafts, and API keys. Pod- and inbox-scoped keys mean one tenant's credentials cannot touch another's data. For deliverability isolation between tenants, give each tenant its own domain or subdomain, since sending reputation is per domain.

6. Wire it into your framework

AgentMail ships an MCP server so tools like Claude Code can use email directly, plus integrations for LangChain, Google ADK, Replit, LiveKit, and others. If your framework is not on the list, the REST API is the integration surface.

Common pitfalls

  • Sharing a human's mailbox. The agent inherits that person's identity and credentials. Give the agent its own inbox instead.
  • Polling instead of subscribing. Polling IMAP every few seconds burns rate limits and adds latency. Webhooks or WebSockets deliver the message the moment it arrives.
  • Ignoring webhook verification. An unverified endpoint will accept forged events. Verify signatures before trusting a payload.
  • Assuming pods isolate deliverability. Pods isolate data per tenant. Reputation is per domain, so separate domains or subdomains per tenant when deliverability isolation matters.
  • Skipping rate limit planning. Check the rate limits page before you fan out to thousands of inboxes.
  • Sending from a shared domain in production. Move to a custom domain so your agents build their own sending reputation.
  • Treating every inbound event as trusted input. An inbox is a public input channel. Prompt injection arrives by email the same way it arrives by web form. Validate and scope what your agent does with untrusted message bodies before it acts on them.
  • Hardcoding inbox IDs across services. Pass inbox IDs through configuration or look them up by label, so a staging agent and a production agent never write to the same inbox by accident.

Frequently Asked Questions

Can I use a general-purpose email API for my agent instead? You can send mail with one, but you will not get programmatic inbox provisioning, inbound webhooks, thread context, or per-agent identity. Those are the parts an agent actually needs, and building them yourself is months of SMTP plumbing.

How fast can I provision an inbox? One API call, under a second, with no DNS or domain verification required to get started. The inboxes docs cover the full lifecycle.

Does AgentMail work with my agent framework? Yes. There are integrations for LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, and an MCP server for tool-using agents, plus a REST API for everything else.

What does it cost? The free tier includes 3 inboxes and 3,000 messages. Paid plans start at $20 per month for 10 inboxes. Current tiers are on the pricing page.

Conclusion

Email APIs built for applications solve the sending half of the problem. Agents need the other half: an address they own, inbound mail as events, threads they can read and reply to, and isolation that holds when you have more than one tenant. AgentMail gives you all of that as an API your agent calls like any other tool, and it drops into the framework you already use. Start building and provision your first inbox in an afternoon.

Related Articles