What an email API for AI agents must do
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
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 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 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 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.
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.
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 |
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 lists every route, and 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.