What can I do with an AgentMail inbox? | AgentMail

An AgentMail inbox is a full email account for your AI agent. It has a real address, sends and receives mail, groups messages into threads, and keeps them so your agent can read them back later. You work with it through the REST API, the Python and TypeScript SDKs, the CLI, the MCP server, or standard IMAP and SMTP.

Features marked Labs are in AgentMail Labs. An organization admin joins Labs from Labs in the console sidebar, then switches Agent Armor on separately on the same page. Labs is available in US production (api.agentmail.to), not yet in EU production (api.agentmail.eu).

Sending

Send, reply, reply all, and forward. Start new conversations, reply inside a thread, reply to everyone on it, or forward a message to a person or another agent. See Sending & Receiving Email.
To, CC, and BCC. Each takes one address or a list, so a human can stay copied on what the agent sends.
HTML and plain text. Send both text and html so every email client can display the message. See Messages.
Attachments. Provide each file as Base64 content or as a url that AgentMail downloads. Inline content is limited to 6 MB for the whole request; URL attachments can total around 30 MB per message. See Attachments.
Display name. Set display_name on the inbox to control the sender name recipients see. See Inboxes.
Drafts. Create a draft, let a person or another process review and edit it, then send it. Drafts can also be replies and forwards. See Drafts.
Scheduled send. Set send_at on a draft and AgentMail sends it at that time, with no cron job on your side. Update send_at to reschedule, or set it to null to keep the draft unsent. Scheduling is a draft feature: Send Message always sends immediately. See Scheduled sending.
Safe retries. Send an Idempotency-Key header so a retried send request does not send the email twice. See Idempotency.
Open tracking (private beta). Find out when a message is first opened. It requires a custom domain with tracking enabled and the Developer plan or above, and is turned on by request. See How do I know when an email is opened?.

Receiving

A real address. Anyone can email the inbox. On @agentmail.to this works as soon as the inbox exists; on your own domain, once the domain is verified, unless you set the domain up as send-only.
Threads. Replies are grouped into conversation threads automatically, using standard email headers. See Threads.
Reply extraction. extracted_text and extracted_html hold only the new content of each message, without the quoted history below it. Attachments with extractable text, such as PDF and Word files, also get a text_url. See Reply & Attachment Extraction.
Attachment downloads. Getting an attachment returns a signed download_url for its bytes. See Attachments.
Spam and virus detection. Incoming mail is scanned. Spam is kept but left out of list results unless you ask for it. See Spam & Virus Detection.

Finding and organizing mail

Filtered lists. List messages or threads by label, by time range with before and after, or by text in the sender, recipients, or subject. List Threads without an inbox to see threads across every inbox in your organization. See Threads.
Full-text search. Search Messages searches the messages in one inbox. Search Threads searches the threads in one inbox, in one pod, or across your whole organization. Both rank results by relevance and match the sender, recipients, subject, and body. See Searching threads and Searching messages.
Inbox search. Find inboxes by address or display name with Search Inboxes.
Labels. Add your own labels to messages when you send them or later, then filter by label to track workflow state. See Labels.
Inbox metadata. Attach your own key-value data to an inbox, such as a user or tenant ID. See Metadata.
Pausing. Stop an inbox sending and receiving without deleting it. Mail sent to a paused inbox is not delivered. See Pausing an inbox.

Controlling who an inbox talks to

Allow and block lists. Allow or block addresses and domains for sending, receiving, and replies, for the whole organization, one pod, or one inbox. See Lists and How do I set up allowlists and blocklists?.
Pods. Group inboxes per customer or tenant to keep them isolated from each other. See Pods and How do I use Pods for multi-tenant email?.
Scoped API keys and permissions. Limit a key to one pod or one inbox, and to specific permissions, for example a key that can create drafts but not send them. See Permissions.
Agent Armor (Labs). Scans incoming mail for prompt injection and other attempts to manipulate an agent, and marks each message clear or review. In Hold mode, messages marked review are kept from your agents until someone releases them. See Agent Armor.

Domains

Default domain. Inboxes on @agentmail.to need no setup. The domain is shared by all AgentMail users, and so is its sending reputation.
Custom domains. Send and receive as agent@yourcompany.com after you add the DNS records AgentMail gives you and verify the domain. Available on the Developer plan and above. See How do I set up a custom domain?.
Subdomain inboxes. Enable subdomains on a domain and publish the wildcard MX record AgentMail then lists for it. Once the domain verifies, you can create inboxes on any of its subdomains, such as agent@support.example.com, without adding each one. See How do I create inboxes on any subdomain?.

Events

Webhooks. AgentMail sends a request to your endpoint when a message is received, sent, delivered, bounced, and more. See Webhooks and the event types.
Polling webhooks. Subscribe to the same events and fetch them whenever your agent runs, with no public URL. Available in the US region. See Polling Webhooks.
WebSockets. Keep a connection open and receive events as they happen, with no public URL. See WebSockets.
Metrics. Query counts of sent, delivered, bounced, and other events over time, for your organization, a pod, or one inbox. See Query Events.

Agent identity and onboarding

AgentID. Sign an agent in to apps that support AgentID, or create accounts for it at them, using its inbox as its identity. See AgentID Sign-In and AgentID in Claude, ChatGPT, and Cursor.
Agent sign-up. An agent can sign itself up through the API and receive an API key and an inbox. Until its human verifies it or claims the inbox, it can send only to that human. See Agent Onboarding and How do I claim my agent’s inbox?.

Calendar

Calendar. Every inbox has a calendar: create events, send and receive invitations, and get webhooks as events start and end. See Calendar.

Ways to connect

REST API and SDKs. Install the Python SDK with pip install agentmail or the TypeScript SDK with npm install agentmail. See the API Reference.
CLI. Manage inboxes, messages, and more from a terminal. See CLI.
MCP server. A hosted server at https://mcp.agentmail.to/mcp for Claude, ChatGPT, Cursor, and other MCP clients. See MCP.
Skills. The official AgentMail skill for Claude Code, Cursor, Codex, and other assistants. See Skills.
IMAP and SMTP. Read mail from any IMAP client at imap.agentmail.to on port 993, and send through smtp.agentmail.to on port 465 or 587. The username is the inbox address and the password is an API key. See IMAP & SMTP.

Quick example

import os
from datetime import datetime, timedelta, timezone
from agentmail import AgentMail
from agentmail.inboxes import CreateInboxRequest
client = AgentMail(api_key=os.environ["AGENTMAIL_API_KEY"])
# create an inbox; the client_id makes re-runs reuse it
inbox = client.inboxes.create(
    request=CreateInboxRequest(display_name="Support Agent", client_id="support-agent-v1")
)
# send now, with a human on cc and a label for your own tracking
client.inboxes.messages.send(
    inbox.inbox_id,
    to=["customer@example.com"],
    cc=["manager@example.com"],
    subject="Your support request",
    text="Here is what I found.",
    html="<p>Here is what I found.</p>",
    labels=["support"],
)
# schedule a follow-up in two days: scheduling is a draft feature
client.inboxes.drafts.create(
    inbox.inbox_id,
    to=["customer@example.com"],
    subject="Following up on your support request",
    text="Did the fix work for you?",
    html="<p>Did the fix work for you?</p>",
    send_at=datetime.now(timezone.utc) + timedelta(days=2),
)
# search the inbox
results = client.inboxes.messages.search(inbox.inbox_id, q="support request")
for message in results.messages:
    print(message.subject)