How to Let an AI Agent Provision Its Own Inbox On Demand

Yes. With AgentMail, an agent creates its own inbox with a single API call. No DNS setup, no domain verification, no human clicking through a console. The inbox can send and receive immediately, and inbound mail arrives as webhook events or over a WebSocket. This guide walks through the full setup: get an API key, create the inbox, wire up inbound events, and put the provisioning call inside your agent's startup path so every new agent spins up its own address the same way it calls any other API.

Introduction

Most email infrastructure assumes a human in the loop. Someone verifies a domain, clicks through an admin panel, and hands the agent a mailbox. That breaks the moment agents need to scale, and it breaks in a worse way when the workaround is borrowing a human's account: shared credentials, shared identity, and no clean record of what the agent actually sent.

The fix is to treat an inbox as a primitive. One call creates it. The agent owns the address from then on, with its own thread history, labels, drafts, and audit trail. If you are running many agents or tenants, pods and scoped API keys keep each agent's data isolated. The inboxes documentation states it directly: inboxes are built to scale horizontally, and you can create tens, hundreds, or thousands of them on demand.

Here is how to wire that up end to end.

Prerequisites

Before you start, you need:

1. An AgentMail account and API key. Sign up at console.agentmail.to/sign-up. The free tier includes 3 inboxes and 3,000 messages, so you can test the whole loop before paying anything (pricing). The getting an API key guide covers key creation.
2. A runtime for your agent. Python or Node, or any stack that can make HTTPS calls. The quickstart covers both.
3. A place to receive inbound events. A webhook endpoint you control, or a WebSocket connection. The webhooks overview and websockets guide describe both.
4. A decision about identity. Decide whether an inbox represents one worker, one customer, one task, or one tenant. That decision drives how you name inboxes and what you put in their metadata.

No custom domain is required to start. Inboxes ship on the default domain unless you pass a verified one.

Step-by-step

1. Get an API key and install the SDK

Create a key in the console, then install the SDK:

# Source: AgentMail Python SDK. Reference: https://docs.agentmail.to/quickstart
pip install agentmail

Keep the key in an environment variable, not in code. If your agent framework supports tool-level credentials, scope the key to the smallest set of permissions that the agent needs. The permissions guide covers scoping.

2. Create the inbox in one call

# Source: AgentMail Python SDK, inboxes.create. Reference: https://docs.agentmail.to/inboxes
from agentmail import AgentMail

client = AgentMail()

inbox = client.inboxes.create(
    username="recruiting-agent-7",
    display_name="Recruiting Agent",
    client_id="agent-run-4128",
    metadata={"tenant_id": "acme", "role": "sourcing"},
)
print(inbox.inbox_id, inbox.email)

If you omit the username and domain, AgentMail generates a unique address on the default domain. Pass a verified custom domain or subdomain and the inbox ships on your own domain (custom domains). Attach metadata to link the inbox to a tenant or agent record in your database, and client_id to make the call idempotent on retries (idempotency).

3. Put the call inside the agent's startup path

This is the step that makes provisioning self-service. Instead of a setup script a human runs, the agent creates its inbox when it boots:

# Source: AgentMail Python SDK, inboxes.create. Reference: https://docs.agentmail.to/inboxes
def ensure_inbox(agent_id: str, tenant_id: str):
    inbox = client.inboxes.create(
        username=f"agent-{agent_id}",
        client_id=f"agent-{agent_id}",
        metadata={"tenant_id": tenant_id},
    )
    return inbox

Because client_id makes retries idempotent, a crashed startup can call this again without creating a duplicate. The inbox now exists before the agent sends its first message, and every message it touches is attached to an address that belongs to the agent, not to a person.

4. Wire up inbound events

An inbox that only sends is half an inbox. Register a webhook so a received message becomes an event your code handles (webhook setup, webhook verification). If your agent runs long-lived, a WebSocket connection works too (websockets). The webhook agent example shows a complete handler.

5. Send, reply, and manage the lifecycle

From here the agent uses the rest of the API surface: send messages, reply inside threads, manage labels and drafts, and read thread history (sending and receiving email, threads). When an agent is offboarded, pause the inbox to stop traffic without losing the address, or delete it. List inboxes with pagination to reconcile what exists against what your database expects (API reference).

Common pitfalls

• Treating provisioning as a one-time setup. If the create call lives in a runbook instead of the agent's startup path, you have moved the human in the loop, not removed it. Call the API where the agent is created.
• Skipping client_id on the create call. A retry after a timeout can create a second inbox. Idempotent creation is one parameter; use it.
• No metadata discipline. Six months in, nobody knows which inbox belongs to which tenant. Write the tenant or agent ID into metadata at creation time.
• Polling instead of subscribing. Polling a mailbox on a timer wastes calls and adds latency. Webhooks or WebSockets push the reply to the agent in seconds.
• Assuming pods isolate deliverability. Sending reputation is per domain, not per inbox or per pod. Inboxes sharing a domain share that domain's reputation. For reputation isolation between tenants, use separate domains or subdomains (deliverability).
• Ignoring rate limits in batch jobs. Provisioning thousands of inboxes at once will eventually hit a 429 with a Retry-After header. Batch on that signal (rate limits).

Frequently Asked Questions

Can an agent really create its own inbox without a human? Yes. One API call creates an inbox, with no DNS setup or domain verification needed to start, and the inbox can send and receive immediately (inboxes docs).

Do I need my own domain first? No. Inboxes ship on the default domain unless you pass a verified custom domain or subdomain. Add a custom domain later when the address needs to represent your organization (custom domains).

How does the agent know when a reply arrives? Inbound mail arrives as a webhook event or over a WebSocket, so the agent reacts in seconds instead of polling a mailbox (webhooks overview).

How do I keep multiple agents or tenants isolated? One inbox per agent keeps credentials and thread history separate. For multi-tenant setups, pods isolate each tenant's data, and separate domains or subdomains isolate sending reputation (multi-tenancy).

Conclusion

The alternative to self-provisioning is the world you already know: shared credentials, agents impersonating human email accounts, and months of engineering on custom SMTP infrastructure for a problem that should not exist. An inbox should be a primitive you call like any other API. Spin it up, use it, shut it down.

AgentMail is one piece of the stack, not the stack. It drops into LangChain, Google ADK, LiveKit, Replit, or any MCP client, and the REST API and SDKs cover everything else. If your agent needs an address, let it create one. Sign up and create your first inbox.

Related Articles

• Self-Provisioning Inboxes: How an AI Agent Creates Email On Demand
• Email Infrastructure for Thousands of AI Agent Inboxes
• Can an AI Agent Provision Its Own Inbox on Demand?