AgentMail Docs

Appearance

SOP: Create Your First Inbox ​

Fresh 🌱

An inbox is a scalable, API-first email account with its own address. Create as many as your agents need.

1. Create the inbox ​

bash
# client_id makes the create call safely retryable (idempotent)
curl -X POST https://api.agentmail.to/v0/inboxes \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "my-agent-inbox-v1" }'
# returns { inbox_id, ... }
python
from agentmail import AgentMail
client = AgentMail()  # reads AGENTMAIL_API_KEY

inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
print(inbox.inbox_id)
bash
# CLI
agentmail inboxes create

2. Confirm the address ​

The returned inbox_id is the inbox's email address (for example my-agent@agentmail.to). Use it as the inbox_id in every messages, threads, and drafts call.

bash
curl https://api.agentmail.to/v0/inboxes/<inbox_id> \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

Notes ​

  • On the default agentmail.to domain, inboxes are ready immediately. To send from your own domain, complete Custom Domain Setup first.
  • Sending 10 emails across 100 inboxes generally delivers better than 1000 emails from one inbox.

Related

Inboxes concept · Create Inbox API · Creating your first inbox (KB)