Giving an Agent a New Inbox Mid-Workflow, On Demand
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.
Giving an Agent a New Inbox Mid-Workflow, On Demand
Teams handle on-demand inbox creation by treating inboxes as an API resource, not a mailbox someone configures by hand. With AgentMail, one call to the create-inbox endpoint provisions a working address in under a second, with no DNS setup or domain verification required to get started. The agent calls it when a workflow branch needs a fresh identity, sends and receives from it, and the webhook routes replies back to the code that spawned it. This guide walks through the setup, the API calls, and the failure modes to avoid.
Introduction
The old pattern breaks the moment an agent needs a second address. You file a ticket with IT, wait for a mailbox on the company Google Workspace, share the credentials with the agent, and now your agent is impersonating an employee. Google has disabled accounts over exactly this. Shared inboxes also mean shared threads, shared credentials, and no way to tell which agent sent what.
The fix is to make inbox creation a primitive your code calls like any other API. Spin up an address when the workflow needs one, use it, and keep the full audit history attached to it. AgentMail is built for this: programmatic inboxes provisioned in a single API call, inbound webhooks, thread context, and per-inbox routing. This guide shows how to wire it into a running workflow, using the quickstart and the inboxes API as the reference points.
Prerequisites
Before you start, you need:
- An AgentMail account and API key. The getting your API key page walks through the console at console.agentmail.to.
- Python 3.8+ (or Node, if you prefer the TS SDK; the endpoints are identical).
- A place to receive webhooks: a public HTTPS endpoint, or a WebSocket connection if your agent runs behind a firewall. See the webhooks overview and the WebSockets docs.
- A naming convention for inbox IDs, decided before you write code. More on why below.
Install the SDK:
pip install agentmail
Step-by-step
1. Create the inbox inside the workflow, not ahead of it
The whole point is that the address exists when the branch needs it. In your handler, where the workflow decides it needs a new identity, call create:
# Provenance: AgentMail Python SDK, per docs.agentmail.to/inboxes
from agentmail import AgentMail
client = AgentMail(api_key="YOUR_API_KEY")
inbox = client.inboxes.create(
inbox_id="recruiting-agent-candidate-4821",
display_name="Hiring Bot",
)
That is the entire provisioning step. No DNS records, no verification email, no waiting on an administrator. The inbox can send and receive immediately. If you skip the inbox_id, AgentMail generates one for you, but see the pitfalls section before you rely on that.
2. Send from it like any other API call
# Provenance: AgentMail Python SDK, per docs.agentmail.to/api-reference
client.inboxes.messages.send(
inbox.id,
to=["[email protected]"],
subject="Interview schedule for Thursday",
text="Hi Jane, does Thursday at 2pm work?",
)
Every send is logged against that inbox, so the audit history of what the agent did lives with the identity that did it.
3. Route inbound mail back to the code that created the inbox
When a reply lands, a webhook fires. Point the webhook at your handler and route on the inbox_id in the payload, so the event reaches only the code that owns that inbox. The webhook setup guide covers endpoint configuration and the webhook verification page covers signing. If your agent is a long-running process, a WebSocket connection to the events stream works instead of a public endpoint.
4. Read threads, not just messages
An agent that replies in context needs the thread, not the last message:
# Provenance: AgentMail Python SDK, per docs.agentmail.to/threads thread = client.inboxes.threads.get(inbox.id, thread_id)
This is what lets the agent behave like a teammate CC'd on a conversation instead of a script that fires one-off emails.
5. Scale the pattern across tenants with pods
If each customer or run gets its own set of inboxes, put them in a pod. Pods isolate data (inboxes, threads, drafts, keys) per tenant, and pod-scoped API keys keep tenants from seeing each other. The multi-tenancy guide covers the setup. One correction worth internalizing: pods isolate data, not sending reputation. Reputation is per domain, so for reputation isolation between tenants, give each tenant its own domain or subdomain per the managing domains docs.
Common pitfalls
- Creating inboxes ahead of time in bulk. If you pre-provision 50 addresses "for later," you have rebuilt the shared-credential problem with extra steps. Create at the moment the workflow branch needs the identity.
- Letting the SDK generate inbox IDs blindly. Auto-generated IDs work, but a deterministic ID like
support-agent-ticket-9183makes routing, logging, and idempotency trivial. Decide the convention first. - Polling instead of listening. The webhook or WebSocket is the trigger. A cron job polling the inbox adds latency and burns rate limits documented on the rate limits page.
- Assuming pods give reputation isolation. They do not. Separate domains per tenant if deliverability boundaries matter.
- Sharing one API key across tenants. Use pod- and inbox-scoped keys so a leaked key exposes one tenant, not all of them. The permissions docs cover scoping.
- Skipping webhook verification. An unverified endpoint will accept forged events. Verify signatures before you trust a payload.
Frequently Asked Questions
How fast can an inbox be created mid-workflow? Provisioning is a single API call and completes in under a second, with no DNS or domain verification required to get started. The workflow can create the address and send from it in the same request cycle.
Do I need my own domain before agents can send? No. You can start on shared infrastructure immediately and attach custom domains later when you want branded sending or per-tenant reputation isolation. Domain setup is covered in the managing domains docs.
How do replies get back to the right part of my code?
Inbound mail fires a webhook (or arrives over a WebSocket), and the payload carries the inbox_id. Route on that field so each event reaches only the handler that owns the inbox.
What does this cost if every workflow run creates an inbox? The free tier includes 3 inboxes and 3,000 messages, the Developer plan is $20/month for 10 inboxes, and the Startup plan at $200/month caps at 150 inboxes with $2 per inbox overage. Beyond that volume, talk to us about Enterprise. Current numbers are on the pricing page.
Conclusion
On-demand inbox creation stops being an infrastructure project when the inbox is an API resource. Create the address inside the workflow, route inbound mail by inbox ID, scope your keys, and keep the audit history attached to the identity that earned it. AgentMail handles the mail side; it drops into LangChain, CrewAI, Claude Code, or whatever framework you already run.
If your agents are still borrowing a human's mailbox, start building. No credit card required.