How to Create New Email Inboxes Programmatically for Your Agents
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 Create New Email Inboxes Programmatically for Your Agents
The tools that let an agent create new email inboxes on demand are email APIs built for programmatic provisioning. AgentMail is the clearest example: one API call creates a real inbox that can send, receive, thread, and fire webhooks, with no DNS setup required to get started. This guide walks through setting up AgentMail, creating inboxes from code, wiring inbound events, and scaling the pattern across tenants.
Introduction
Most agents that touch email start by borrowing a human account. That path ends badly: shared credentials, replies from different conversations colliding in one mailbox, and no record of what the agent actually sent. Google has disabled accounts over exactly this pattern.
The fix is to treat an inbox as a primitive your code can call. Spin one up when an agent needs an identity, use it, and keep a full audit history of everything that moved through it. AgentMail is an email API built for that model: inboxes provisioned in a single API call, inbound webhooks and WebSockets, threads, drafts, labels, and attachments, plus pods for multi-tenant isolation. This guide covers the setup end to end.
Prerequisites
- An AgentMail account. Sign up at the console; no credit card required. The free tier includes 3 inboxes and 3,000 messages.
- An API key. Follow getting your API key and store it in your environment, not your repo.
- Python 3.8+ or Node 18+. The SDKs are thin wrappers over the REST API, so anything that can make HTTPS calls works too.
- Optional: a custom domain if you want inboxes on your own domain instead of a shared one. See managing domains.
Step-by-step
1. Install the SDK
pip install agentmail
Provenance: AgentMail Python SDK, per the quickstart.
2. Create an inbox in one call
from agentmail import AgentMail client = AgentMail() # reads AGENTMAIL_API_KEY from the environment inbox = client.inboxes.create() print(inbox.inbox_id, inbox.email)
Provenance: AgentMail Python SDK, per the inboxes docs.
No DNS verification, no domain warmup, no waiting period. The inbox exists and can receive mail immediately. If you want a readable address, pass a display_name or provision inboxes on a custom domain.
3. Send and reply from that inbox
client.inboxes.messages.send(
inbox.id,
to=["[email protected]"],
subject="Quote ready",
text="Your quote is attached.",
)
# Reply inside an existing thread
client.inboxes.messages.reply(inbox.id, message_id, text="Got it, on it.")
Provenance: AgentMail Python SDK, per the API reference.
4. React to inbound mail
An inbox is only useful if your agent acts on what arrives. Two options:
- Webhooks: register an HTTPS endpoint and AgentMail POSTs an event for every inbound message. Verify the signature per the webhook verification guide.
- WebSockets: hold a persistent connection and receive events with no public endpoint. Better for local development and agents that live behind a firewall.
5. Scale to one inbox per agent or tenant
When you are provisioning inboxes dynamically, say one per support ticket or one per recruiting candidate, group them into pods. Pods isolate data per tenant: inboxes, threads, drafts, and API keys stay walled off, and webhook routing can be scoped per inbox. Use pod- or inbox-scoped API keys so a leaked key exposes one tenant, not all of them.
A concrete example: a recruiting agent creates one inbox per candidate, links it to the candidate record in Ashby or Greenhouse, and every reply lands as a webhook event scoped to that candidate. When the search closes, retire the inbox and the audit history stays intact.
One correction worth internalizing early: sending reputation is per domain, not per inbox. If two tenants share a domain, they share that domain's reputation. For real reputation isolation, put tenants on separate domains or subdomains.
Common pitfalls
- Borrowing a human mailbox "just for now." It never stays temporary, and it couples your agent's identity to someone's personal account. Create a dedicated inbox instead; it costs one API call.
- Polling instead of subscribing. Polling IMAP every 30 seconds burns rate limits and adds latency. Webhooks or WebSockets deliver the event the moment mail lands.
- Treating pods as a deliverability feature. Pods isolate data, not reputation. Reputation follows the domain.
- Provisioning inboxes with no lifecycle. If inboxes are ephemeral, decide when they get retired. Unbounded creation hits plan caps: the Startup tier caps at 150 inboxes, then bills $2 per inbox overage, so check the pricing page before you build a per-user model.
- Skipping webhook verification. An unverified endpoint will accept forged events. Verify signatures before your agent acts on a payload.
Frequently Asked Questions
Can an agent really create an inbox at runtime, or do I have to pre-create them in a dashboard?
At runtime. client.inboxes.create() is a normal API call your agent makes whenever it needs a new identity. No dashboard, no approval step, no DNS verification to get started.
Do I need my own domain before I can create inboxes? No. Inboxes work immediately on AgentMail's infrastructure. Add a custom domain later when you want addresses on your brand, using the domain management docs.
How do I keep one customer's mail separate from another's? Group each tenant's inboxes into a pod and issue pod-scoped API keys. Data, threads, and webhook routing stay isolated per tenant. For sending reputation, use separate domains or subdomains per tenant.
What does it cost to run many inboxes? The free tier includes 3 inboxes and 3,000 messages. Developer is $20/month for 10 inboxes, and Startup is $200/month up to 150 inboxes with $2 per inbox overage beyond that. Enterprise pricing covers larger volumes.
Conclusion
Giving an agent an inbox used to mean months of SMTP infrastructure or borrowing a human's Gmail. It is now a single API call: create the inbox, subscribe to inbound events, and let the agent own its identity and its audit trail. If your agents need email, create your first inbox and see how long it takes. It is under a second.