An email API an agent can actually drive
Scoped keys, idempotent writes, Stripe-shaped errors, a native Model Context Protocol (MCP) server, and real-time inbound. The contract a machine can act on safely.
import { AgentMail } from "@agentmail/sdk"
const mail = new AgentMail({ apiKey: process.env.AGENTMAIL_KEY })
// Your agent's first call — send from a managed mailbox.
await mail.messages.send({
mailbox: "agent@acme.dev",
to: "user@example.com",
subject: "Your verification code",
text: "Reply with APPROVE to continue.",
})Your agent's first call — over REST or MCP.
Native MCP: a mailbox as tools
We run a native MCP server over a streamable-HTTP transport. Point your MCP client at the advertised endpoint, authenticate with a mailbox API key, and the mailbox's actions become tools your agent can call — no custom integration code.
{
"mcpServers": {
"agentmail": {
"type": "streamable-http",
"url": "https://mail.sairaph.com/app/mcp",
"headers": {
"Authorization": "Bearer ${AGENTMAIL_MAILBOX_KEY}"
}
}
}
}An MCP client config pointed at your mailbox.
A REST API built for machines
Issue an API key scoped to one mailbox with a read, send, or admin role, with optional expiry. Send Idempotency-Key on mutating calls so retries don't double-execute. Read errors from a Stripe-shaped envelope. Hit the limit and you get a 429 with Retry-After. Read inbound from cache, or ?live=true for an on-demand fetch.
# Issue a scoped, optionally-expiring key from the dashboard,
# then send — idempotently — over REST.
curl https://mail.sairaph.com/app/api/v1/messages \
-H "Authorization: Bearer $AGENTMAIL_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d mailbox="agent@acme.dev" \
-d to="user@example.com" \
-d subject="Your verification code" \
-d text="Reply with APPROVE to continue."Tabbed samples — issue a key, send, read.
Real-time inbound, for the agent waiting on a code
A long-lived IMAP IDLE watcher surfaces new mail in near real time, with a periodic poll as a fallback. When your agent is blocking on a one-time code, ?live=true fetches the body straight from the source.
# Blocking on a one-time code? Fetch the body straight from source.
curl "https://mail.sairaph.com/app/api/v1/messages?mailbox=agent@acme.dev&live=true" \
-H "Authorization: Bearer $AGENTMAIL_KEY"Poll for an OTP with ?live=true.
Three steps to your first email
Verify your account, issue a scoped key, make your first call — over REST or MCP.
Reference and status
The full OpenAPI reference is published as a Scalar docs site, generated from our live schema, with interactive Swagger at /docs. Live service status is on the status page.