What can I do with an AgentMail inbox?

An AgentMail inbox is a full email account for your AI agent. Each inbox gets a unique email address and can send, receive, reply, forward, and manage emails entirely through the API.

Sending

• Send emails to anyone on the internet
• CC and BCC AI agents in email threads
• Forward emails to humans and AI agents
• Create and send drafts
• HTML and plain text
• Attachments with Base64 encoding (PDFs, images, documents)
• Custom display names
• Labeling email threads
• Schedule send emails for later

Receiving

• Receive emails from anyone: your inbox has a real email address
• Webhooks for real-time notifications when an email arrives
• WebSockets for persistent event streaming without needing a public URL
• Spam and virus detection on all incoming emails
• Attachment downloads to programmatically access files from received emails
• Reply extraction with built-in extracted_text and extracted_html fields that strip quoted text

Threading and conversations

• Automatic threading: replies are grouped into conversation threads using standard email headers
• Reply-to messages to maintain context in multi-turn conversations
• Reply all to respond to all recipients on a thread
• Forward messages to other addresses or agents
• Org-wide thread listing to query conversations across every inbox in your organization

Organization and filtering

• Labels: add custom string tags to messages (e.g., urgent, sales, needs-response)
• Filter by label: list only messages or threads matching specific labels
• Allowlists and blocklists: control who an inbox can send to and receive from
• Pods: isolate groups of inboxes per customer for multi-tenant applications

Identity and authentication

• Custom domains: send from your own domain (e.g., agent@yourcompany.com) instead of @agentmail.to
• SPF, DKIM, and DMARC: full email authentication for production deliverability
• Idempotent inbox creation: use the client_id parameter to safely create inboxes without duplicates

Access methods

• REST API: full CRUD on inboxes, messages, threads, drafts, and attachments
• Python SDK: pip install agentmail
• TypeScript SDK: npm install agentmail
• SMTP: connect email clients or existing systems for sending
• MCP Server: use with Claude Code, Cursor, and other AI coding tools
• IMAP: coming soon

Quick example

1
from agentmail import AgentMail
2
3
client = AgentMail()
4
5
# Create an inbox with a display name
6
inbox = client.inboxes.create(display_name="Support Agent")
7
8
# Send an email with a human CC'd
9
client.inboxes.messages.send(
10
    inbox_id=inbox.inbox_id,
11
    to=["customer@example.com"],
12
    cc=["manager@yourcompany.com"],
13
    subject="Your support request #1234",
14
    text="Hi! I've reviewed your request and here is what I found...",
15
    html="<p>Hi! I've reviewed your request and here is what I found...</p>",
16
    labels=["support", "tier-1"]
17
)
18
19
# Check for replies
20
threads = client.inboxes.threads.list(inbox_id=inbox.inbox_id)
21
22
if threads.threads:
23
    # Get the full conversation
24
    thread = client.threads.get(thread_id=threads.threads[0].thread_id)
25
26
    # Reply to the latest message
27
    client.inboxes.messages.reply(
28
        inbox_id=inbox.inbox_id,
29
        message_id=thread.messages[-1].message_id,
30
        text="Following up: have you had a chance to try the fix?",
31
        html="<p>Following up: have you had a chance to try the fix?</p>"
32
    )