Solutions for agent builders
Email API for AI agent builders
Move agents from demo to production. Give each agent a real mailbox, authorised sending tools, clean reply content, and live mailbox events.
Start with Product MCP for the first loop. Then reuse the same public APIs (Sending, Mailbox, clean content, and event streams) as the workflow grows.
No broad manual key by default. Scope tools to product surfaces and mailbox sets.
First workflow
scoped grant active<TL;DR for AI agents>
A working mail loop agents can read.
What the agent gets
- MCP exposes authorised Sendmux tools for Mailbox, Management, and Sending.
- The Sending API accepts single or batch mail with idempotency keys.
- The Mailbox API lets an agent read clean content and hold an event stream open.
Connect the smallest safe tool set first, then reuse the same public APIs as the workflow grows.
$ curl https://smtp.sendmux.ai/api/v1/emails/send \ -H "Authorization: Bearer $SENDMUX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: agent-demo-run" \ -d '{ "from": "agent@yourdomain.dev", "to": "inbox@yourdomain.dev", "subject": "Agent handoff", "html_body": "<p>Run complete.</p>" }'
Getting started
Give the agent one job first.
Give the agent the smallest useful surface first. Hosted MCP works when your client supports remote MCP and OAuth. Direct API calls are still available when you need a specific endpoint, custom retry logic, or app-side control.
Step 1 of 3
Connect hosted MCP
Connect hosted MCP so the agent sees only the tools allowed by its grant.
Agent tool flow
Tools stay inside the grant.
Agents should not receive broad keys by default. Connected apps use short-lived access tokens, rotating refresh tokens, product-surface selection, and mailbox-set selection before an agent can call a tool. Build a grant below and watch the exposed tools change.
Configure the grant
Simulate a tool call
"grant": { "surfaces": ["mailbox", "sending"], "mailbox_sets": ["support@yourdomain.dev"], "access_token": "short-lived", "refresh_token": "rotating" }, "tools": [ "GET /mailbox/messages", "GET /mailbox/messages/:id/content", "GET /mailbox/events", "POST /emails/send (single + batch)" ]
→ POST /emails/send 200 OK # tool call allowed within grant
If several mailboxes are granted and the request omits mailbox_id, Sendmux returns 400 missing_parameter. Outside the grant, it returns 403 insufficient_permissions.
API surface proof
Direct APIs when the agent needs control.
The same product surfaces are available outside MCP. Use single send for one message, batch send for grouped work, mailbox content endpoints for clean replies, and mailbox events for live reactions.
$ curl https://app.sendmux.ai/api/v1/mailbox/events \ -H "Authorization: Bearer $MAILBOX_TOKEN" \ -H "Last-Event-ID: evt_previous" : ping event: message id: evt_8a31 data: { "type": "arrival", "mailbox": "support@yourdomain.dev" } : ping event: message id: evt_8a32 data: { "type": "arrival", "mailbox": "ops@yourdomain.dev" }
Send-only and mailbox keys can make 1,800 Sending API requests per 60 seconds.
A batch send can include 1 to 100 messages and still counts as one request.
A single email request can include up to 10 attachments in the payload.
Mailbox event streams use a 30 second ping by default, with 10 to 300 second bounds.
Event stream shown is illustrative: message arrivals and 30 second pings.
Inbox event loop
Replies arrive messy. Agents need clean input.
Email replies arrive messy. Agents need content that is easier to inspect, plus an event path that avoids polling. Sendmux gives both: clean message and thread content endpoints, and a mailbox event stream that can resume after a disconnect. Toggle the controls to see the cleaned payload change.
Hi there, Yes, go ahead and provision the new mailbox. The agent can start the run tonight. Confirm here: https://app.example.dev/runs/8842 On Tue, 11 Jun, Agent <agent@yourdomain.dev> wrote: > Run is queued. Reply YES to provision the > mailbox and I will kick off the first send. -- Priya Nair Head of Ops, Hexa Labs +61 2 5550 1234
{
"text": "Hi there,\n\nYes, go ahead and provision the new mailbox.\nThe agent can start the run tonight.\n\nConfirm here: https://app.example.dev/runs/8842",
"links": ["https://app.example.dev/runs/8842"],
"chars": 141
}Signature and quote stripping on by default.
Resume with Last-Event-ID, no polling.
Bound a session with close_after.
Builder kit
Pick the surface that matches the job.
MCP is the fastest fit for tool-capable agents. API calls fit app code. CLI commands help with setup checks. Agent skills give coding agents a repeatable operating note.
Hosted MCP
Connect once, grant selected product surfaces and mailboxes, then let the agent call only the tools it is allowed to use.
mcp connect product ✓ tools scoped to grant
Common questions
What agent builders ask first.
Sendmux is an email API for AI agent builders. It gives agents authorised ways to send mail, read mailbox data, fetch clean content, and hold a live event stream. Builders can start with hosted MCP, then call the same public APIs from an app when the workflow needs more control.
Yes. Hosted MCP is documented for clients that support remote MCP and OAuth. It exposes curated Mailbox, Management, and Sending tools based on the connected-app grant, so the agent does not need a long-lived manual API key. Use raw APIs, SDK packages, or CLI commands when you need endpoints beyond the curated tool list.
Yes. Sending and mailbox access are separate surfaces, but they can be granted together. An agent can send through POST /emails/send, read mailbox state through mailbox endpoints, and subscribe to GET /mailbox/events for live updates. MCP can expose these allowed actions from one grant.
Connected apps use short-lived access tokens with rotating refresh tokens. During authorisation, you choose product surfaces and mailbox sets. If several mailboxes are granted and a request omits mailbox_id, Sendmux returns 400 missing_parameter; outside the grant, it returns 403 insufficient_permissions. That keeps agent access narrow.
Yes. The clean content endpoints return message or thread content with controls such as part, max_body_chars, strip_signature, strip_quotes, include_links, and include_html. Signature stripping, quote stripping, and link extraction are on by default, while HTML is off by default. But raw body endpoints remain available.
Use GET /mailbox/events when an agent needs a live stream. It accepts event_types, last_event_id, ping, close_after, Last-Event-ID, and mailbox_id. The default ping is 30 seconds, with bounds from 10 to 300 seconds, and invalid event types return 400 invalid_parameter.
Email API for AI agent builders
Move agent email from demo to production.
Start with MCP for the first loop, then keep mailbox, sending, clean content, and event paths as the app grows.