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.

JobSending APIEmail API for agents
Send a messageYesYes
Create an address on demandNoYes, with one call
Receive and store mailOften forwarded to a webhook, one message at a timeStored in an inbox
Thread repliesUsually left to youDone for you
Wait for the next messageNoA waiting call, a webhook or a stream
Extract codes and linksNoParsed on arrival
Screen what a model will readNot its jobShould 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.

WayHow it worksSuits
A waiting callOne request stays open until the next message arrivesAn agent expecting one email, such as a sign-up code
A webhookThe API posts each event to your HTTPS endpointA server that is always on
An event streamThe agent holds one connection open and reads eventsAn 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.

PartCall or field
CreatePOST /v1/agents/signup with no account, or POST /v1/inboxes
ReceiveGET /v1/inboxes/{id}/messages and GET /v1/messages/{id}, with attachment text
ThreadGET /v1/threads/{id}/context and extracted_text
WaitGET /v1/inboxes/{id}/wait, signed webhooks, GET /v1/events/stream
Extractextracted.codes, extracted.verify_links, extracted.events
ScreenA verdict on every message, the safe view, and held mail withheld from keys
SendPOST /v1/messages/{id}/reply and POST /v1/inboxes/{id}/messages, screened before they leave
TypeScript, with the trotta-mail package
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.

Sources

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