# Email REST API for AI agents, with curl examples

> A REST API that gives an AI agent its own inbox. Four curl calls: sign up with no account, wait for inbound email, read a screened safe view and reply.

Source: https://trotta.email/integrations/rest-api

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 November 20, 2026

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

```bash
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'
```

201 Created:

```json
{
  "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.

```bash
curl -G https://api.trotta.email/v1/inboxes/inb_7Qh2mXc4/wait \
  -d timeout=60 \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY"
```

200 OK (trimmed):

```json
{
  "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:

```bash
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.

```bash
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. |

A held message, as a key reads it (trimmed):

```json
{
  "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](https://trotta.email/docs/api): every route, field and error.
- [Webhooks](https://trotta.email/docs/webhooks): register an HTTPS endpoint and get a signed event when mail arrives.
- [Live events](https://trotta.email/docs/events): the same events over a stream, with no public endpoint.
- [Pods](https://trotta.email/docs/pods): one isolated workspace per customer. A key in a pod reaches that pod and nothing outside it.
- [Domains](https://trotta.email/docs/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

- [Trotta Mail guide for agents (llms.txt)](https://api.trotta.email/llms.txt)
- [Trotta Mail OpenAPI description](https://api.trotta.email/openapi.json)

## Related

- [API reference](https://trotta.email/docs/api) Docs
- [An email MCP server for any MCP client](https://trotta.email/integrations/mcp) Integrations
- [Give an AI agent an email address](https://trotta.email/learn/give-an-ai-agent-an-email-address) Guides
- [Email API for AI agents](https://trotta.email/learn/email-api-for-ai-agents) Guides
- [Email webhooks vs polling](https://trotta.email/learn/email-webhooks-vs-polling) Guides
- [Credential phishing](https://trotta.email/threats/credential-phishing) Threat library

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

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
