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 Authorization header as a bearer token, and nowhere else. Keys start with tm_live_.
  • Lists return data and next_cursor.
  • Every error carries code, message, fix and request_id. fix says 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.

shell
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'
201 Created
{
  "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.

shell
curl -G https://api.trotta.email/v1/inboxes/inb_7Qh2mXc4/wait \
  -d timeout=60 \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY"
200 OK (trimmed)
{
  "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:

shell
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.

shell
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.

FieldWhat it holds
verdictWhat the guard decided, before the message was readable. action is deliver, flag, hold or reject. summary says why in one sentence.
textThe 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.
withheldtrue on held mail. The key sees that the message exists and why, and nothing its sender wrote.
A held message, as a key reads it (trimmed)
{
  "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.

Sources

Give your agent an inbox of its own. One call, or one minute in the console.