An email REST API for AI agents
The Trotta Mail REST API gives an AI agent its own inbox with one call that needs no account, then receives, reads and sends mail over HTTPS with a bearer key. Inbound mail is screened before delivery, so every message your code reads carries a verdict, and dangerous mail is held for a human.
Updated
Connect
The API lives at https://api.trotta.email/v1 and speaks JSON over HTTPS. There is nothing to install: every example here is curl.
- A key goes in the
Authorizationheader as a bearer token, and nowhere else. Keys start withtm_live_. - Lists return
dataandnext_cursor. - Every error carries
code,message,fixandrequest_id.fixsays what to do next. - The machine-readable description is at
https://api.trotta.email/openapi.json.
A complete example: inbox, wait, read, reply
This example gets an inbox, waits for a message, reads it and replies. Every Trotta Mail integration page runs the same four steps, so you can compare them. Here each step is one request.
1. Get an inbox
POST /v1/agents/signup needs no key and no body. It returns an organization, an inbox and an API key. Send name to choose the address.
curl -X POST https://api.trotta.email/ v1/ agents/ signup \
-H "Content-Type: application/ json" \
-d '{"name": "riley"}'{
"api_key": "tm_live_9fK2c0aW...",
"organization": { "id": "org_5mTz81Qd", "plan": "agent" },
"limits": { "send_per_day": 50, "inboxes": 2 },
"inbox": {
"id": "inb_7Qh2mXc4",
"address": "riley@trotta.email",
"kind": "agent",
"guard_mode": "guard"
},
"claim_url": "https://trotta.email/ claim/ tmc_8HEoz36w..."
}Keep the api_key: it is shown once. Put it in TROTTA_MAIL_API_KEY. The claim_url is for the human responsible for the agent, and it works for 30 days.
2. Wait for a message
GET /v1/inboxes/{id}/wait holds the request open until the next message is delivered, or the timeout passes. There is no webhook to host and no list to poll.
curl -G https://api.trotta.email/ v1/ inboxes/ inb_7Qh2mXc4/ wait \
-d timeout=60 \
-H "Authorization: Bearer $TROTTA_MAIL_API_KEY"{
"message": {
"id": "msg_8Kd2pXw1",
"thread_id": "thr_2bN8pLw1",
"from": { "address": "megan@trotta.io", "name": "Megan Park" },
"subject": "Thursday review",
"text": "Hi Riley, can you confirm Thursday at 3pm?",
"withheld": false,
"verdict": { "action": "deliver", "level": "safe" }
},
"timed_out": false
}The timeout is 30 seconds by default and 60 at most. On a timeout the call returns message: null and timed_out: true. Call it again. Filter with from, subject or has_code.
3. Read it
The wait call already returns the whole message. To read any message again by its id:
curl https://api.trotta.email/ v1/ messages/ msg_8Kd2pXw1 \
-H "Authorization: Bearer $TROTTA_MAIL_API_KEY"Verification codes are already parsed at extracted.codes, and confirmation links at extracted.verify_links.
4. Reply
Reply inside the thread. Recipients, subject and threading headers are set for you.
curl -X POST https://api.trotta.email/ v1/ messages/ msg_8Kd2pXw1/ reply \
-H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
-H "Content-Type: application/ json" \
-d '{"text": "Thanks, that works."}'Outgoing mail is screened too. A message that contains a secret is not sent: the call returns 422 outbound_blocked with the verdict.
What your agent reads
A key reads screened mail. Three fields on every message say what your code is looking at.
| Field | What it holds |
|---|---|
verdict | What the guard decided, before the message was readable. action is deliver, flag, hold or reject. summary says why in one sentence. |
text | The safe view: only what a human could see. Hidden text is removed, instructions aimed at a model are replaced by a note, and risky links are defanged. |
withheld | true on held mail. The key sees that the message exists and why, and nothing its sender wrote. |
{
"id": "msg_5Tn1vQa9",
"status": "held",
"subject": "",
"text": null,
"withheld": true,
"verdict": {
"action": "hold",
"level": "danger",
"summary": "Held by Trotta Guard until a human reviews it. Reason: instructions aimed at an AI, hidden content.",
"categories": ["prompt_injection", "hidden_content"]
}
}The safe view matters when the next reader is a model. A model may act on an instruction it finds in an email, including one hidden where no human would see it. With the safe view, your code never has that text to pass on, and a held message gives it nothing the sender wrote.
No filter catches everything, so treat mail content as data, never as instructions. A human releases held mail, and the agent that was waiting then receives the message late.
Going further
- API reference: every route, field and error.
- Webhooks: register an HTTPS endpoint and get a signed event when mail arrives.
- Live events: the same events over a stream, with no public endpoint.
- Pods: one isolated workspace per customer. A key in a pod reaches that pod and nothing outside it.
- Domains: agent inboxes on your own domain, on paid plans.
Questions
Can I receive email with curl and no webhook?
Yes. GET /v1/inboxes/{id}/wait holds the request open until the next message is delivered, for up to 60 seconds. On a timeout it returns message null and timed_out true, and you call it again.
Does an AI agent need an account to get an API key?
No. POST /v1/agents/signup needs no account, no key and no body. It returns an inbox, an API key and a claim_url that a human can open later to take responsibility for the agent.
How does the API authenticate requests?
With an API key sent in the Authorization header as a bearer token. A key is never accepted in a query parameter.
What can an agent send before a human claims it?
It can receive from anyone, reply to anyone whose mail to it arrived authenticated, and write to inboxes in its own organization. Any other recipient returns 403 recipient_not_allowed until a human opens the claim_url.
Is there an OpenAPI description?
Yes, at https://api.trotta.email/openapi.json. A short plain text guide for agents is at https://api.trotta.email/llms.txt.