# Email API for AI agents: what it must do

> What an email API for AI agents does that a sending API does not: receive and store mail, keep threads, wait for a message, extract codes and screen.

Source: https://trotta.email/learn/email-api-for-ai-agents

An email API for AI agents lets software own an inbox: create addresses, receive and store mail, keep threads, wait for the next message, pull out verification codes and reply. A sending API covers only outgoing mail. Because a model acts on what it reads, the API should also screen mail before the agent sees it.

Updated November 20, 2026

## What is an email API for AI agents?

An email API for AI agents is an API for a whole inbox, not for a send button. The agent creates an address, receives mail at it, reads each message as structured data and answers in the same thread.

The category is new and the names vary: agent inbox API, inbox API, inbound email API. One test sorts them. If the API cannot hold a two-way conversation without storage and code of your own, it is a sending API.

[What is an agent inbox](https://trotta.email/learn/what-is-an-agent-inbox) defines the thing such an API gives an agent.

## What does a sending API leave out?

A sending API is built to deliver outgoing mail well: receipts, alerts and newsletters. That is a real job, and an agent that only sends notifications needs nothing more.

An agent that holds a conversation needs the other half.

| Job | Sending API | Email API for agents |
| --- | --- | --- |
| Send a message | Yes | Yes |
| Create an address on demand | No | Yes, with one call |
| Receive and store mail | Often forwarded to a webhook, one message at a time | Stored in an inbox |
| Thread replies | Usually left to you | Done for you |
| Wait for the next message | No | A waiting call, a webhook or a stream |
| Extract codes and links | No | Parsed on arrival |
| Screen what a model will read | Not its job | Should be, and before delivery |

[Sending APIs compared](https://trotta.email/compare/sending-apis) goes deeper on where each one fits.

## Receive: an inbox, not a parse hook

Receiving means the API accepts mail for the agent's address and keeps it. The agent can list messages, search them and read one again later.

Each message should arrive parsed: sender, recipients, subject, text, attachments and links as fields. A model should never have to read raw MIME.

Attachments count too. Invoices and contracts arrive as files, so the API should return the text inside a PDF or a Word file, not only the bytes.

## Thread: the conversation as one object

Threading groups a reply with the messages before it. Without it the agent answers each mail as if it were new.

A good API sets the threading headers on a reply and returns the whole conversation in one call. Two details save tokens and mistakes.

- **The new part only.** A reply quotes everything under it. The API should return what the sender wrote this time, without the quoted history and the signature.
- **Model-ready context.** The thread as one text block, with clear boundaries around mail content, so the model can tell data from instructions.

## Wait: how the agent learns mail has arrived

An agent can learn about new mail in three ways. An API for agents should offer all three.

| Way | How it works | Suits |
| --- | --- | --- |
| A waiting call | One request stays open until the next message arrives | An agent expecting one email, such as a sign-up code |
| A webhook | The API posts each event to your HTTPS endpoint | A server that is always on |
| An event stream | The agent holds one connection open and reads events | An agent with no public endpoint |

Webhooks should be signed, and retried when the endpoint is down. [Webhooks vs polling](https://trotta.email/learn/email-webhooks-vs-polling) compares the three in detail.

## Extract: codes and links without a prompt

Agents sign up for services, and services answer with a verification code or a confirmation link. Asking a model to find a six-digit code in an email works most of the time, which is not enough.

The API should parse codes and links on arrival and return them as fields. Then the agent reads a value instead of guessing. See [verification codes for AI agents](https://trotta.email/learn/verification-codes-for-ai-agents).

## Screen: check mail before a model reads it

Screening is the part few email APIs treat as their job, and the part an agent needs most. A model acts on what it reads, and anyone can write to an inbox.

The OWASP Top 10 for LLM Applications lists prompt injection as LLM01, the top risk, in both the 2025 edition and the current 2026 edition. An email is the simplest way to deliver one: text hidden from a human, in the body or in an attachment, written for the model. See [hidden text in email](https://trotta.email/threats/hidden-text-in-email).

Ask three things of any email API an agent will read from.

- **When is mail checked?** Before delivery, or after the agent already has it.
- **What does the agent read?** The raw message, or a safe view with hidden text removed.
- **Is outgoing mail checked?** A hijacked agent leaks data by sending it.

## How Trotta Mail covers each part

Trotta Mail is a pre-delivery inbox: every message is screened while the sending server is still connected. Attacks, known and new, are refused at the door or held for a human. Everything else is delivered with a verdict.

| Part | Call or field |
| --- | --- |
| Create | `POST /v1/agents/signup` with no account, or `POST /v1/inboxes` |
| Receive | `GET /v1/inboxes/{id}/messages` and `GET /v1/messages/{id}`, with attachment text |
| Thread | `GET /v1/threads/{id}/context` and `extracted_text` |
| Wait | `GET /v1/inboxes/{id}/wait`, signed webhooks, `GET /v1/events/stream` |
| Extract | `extracted.codes`, `extracted.verify_links`, `extracted.events` |
| Screen | A `verdict` on every message, the safe view, and held mail withheld from keys |
| Send | `POST /v1/messages/{id}/reply` and `POST /v1/inboxes/{id}/messages`, screened before they leave |

TypeScript, with the trotta-mail package:

```typescript
import { TrottaMail } from "trotta-mail";

// No key needed: this creates the key and the inbox.
const mail = await TrottaMail.signup({ name: "riley" });

const msg = await mail.inboxes.wait(mail.inbox.id, { hasCode: true, timeout: 60 });
if (!msg) throw new Error("No mail arrived within 60 seconds");
msg.extracted.codes[0].value;

const ctx = await mail.threads.context(msg.thread_id); // ctx.context, ctx.trust

await mail.messages.reply(msg.id, { text: "..." });
```

The same calls work over plain HTTP from any language, and as MCP tools. The [API reference](https://trotta.email/docs/api) lists every route, and [webhooks](https://trotta.email/docs/webhooks) covers events and signatures.

The limits are worth knowing. Trotta Mail has no IMAP or SMTP access for mail clients. And no filter catches everything: a reworded scam with no technical tell can still be delivered, so uncertain mail is held for a human.

## Questions

### What is the difference between an email API and an inbox API?

An email API usually means a sending API: it delivers outgoing mail. An inbox API gives software a stored mailbox with an address, threads and inbound mail, which is what an agent holding a conversation needs.

### Can I use an inbound parse webhook for an LLM?

Yes, for simple cases. An inbound parse webhook hands you one message at a time, so storage, threading and screening are yours to build before a model reads the text.

### Does an AI agent need IMAP?

No. IMAP was made for mail apps that sync folders, and an agent is better served by an API that returns parsed messages and says when mail arrives. Trotta Mail has no IMAP or SMTP access for mail clients.

### How does an agent receive email in real time?

Through a webhook, an event stream, or a call that waits for the next message. Trotta Mail offers all three, and each event carries the safe view of the message.

### Is there an MCP server for email?

Yes. Trotta Mail's MCP server is at https://api.trotta.email/mcp and takes an API key or an OAuth sign-in. Its tools read, wait, send, reply and draft, and they return the safe view.

## Sources

- [OWASP Top 10 for LLM Applications 2026, the current edition (published August 2026)](https://genai.owasp.org/resource/owasp-genai-llm-top-10-2026/)
- [OWASP Top 10 for LLM Applications 2025, LLM01: Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/)

## Related

- [API reference](https://trotta.email/docs/api) Docs
- [Webhooks](https://trotta.email/docs/webhooks) Docs
- [Email webhooks vs polling: four ways an agent learns that mail arrived](https://trotta.email/learn/email-webhooks-vs-polling) Guides
- [Sending APIs](https://trotta.email/compare/sending-apis) Compare
- [Hidden text in email](https://trotta.email/threats/hidden-text-in-email) Threat library
- [TypeScript](https://trotta.email/integrations/typescript) Integrations

Give your agent an inbox of its own. Free for two inboxes. No card.

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