The AI agent inbox API.

When someone replies to your agent, you get a structured event, not a MIME blob, with its injection score and sender reputation.

Received mail

Let your agent read its mail

Every message to your agent lands as structured data: the sender, the reply text without the quoted history, SPF and DKIM results, and the files. Read it over the API, or have it pushed to you as an event.

import { createClient } from "@mailsai/sdk";

const mails = createClient(); // reads MAILS_API_KEY

const { data } = await mails.received.list({ limit: 20 });
for (const message of data) {
  console.log(message.from.address, message.subject);
}

Threads

See every conversation in one place

Inbound mail and your agents' replies are threaded by In-Reply-To, so you can read a whole conversation and answer it from the dashboard.

The Threads page of the dashboard: one line per conversation, with who it is with, its labels and its subject

Files

Read every attachment

Each received message lists its files with their name, type and size. Download any of them by id and hand the PDF to your parser.

import { createClient } from "@mailsai/sdk";

const mails = createClient();
const api = "https://api.mails.ai/v1/messages/received";
const headers = {
  Authorization: `Bearer ${process.env.MAILS_API_KEY}`,
};

const { data } = await mails.received.list({ limit: 1 });
const url = `${api}/${data[0].id}/attachments`;

const files = await (await fetch(url, { headers })).json();
for (const file of files.data) {
  if (file.content_type !== "application/pdf") continue;
  const pdf = await fetch(`${url}/${file.id}`, { headers });
  const bytes = await pdf.arrayBuffer(); // hand it to your parser
}

How it works

Structured events, not raw MIME

The inbox API turns every inbound message into a structured event: Cloudflare Email Routing hands each message to our edge worker, and your app gets the event.

  • One structured event

    Inbound is parsed, scored for prompt injection and written as one event.

  • Webhook or SDK reactor

    The same payload by signed HTTPS webhook or a server-sent event stream.

  • Threads and files

    Replies link to their send by In-Reply-To. Files come with their metadata.

Set up

Get started with inbound

Three steps to events in your app: register a webhook, or use the SDK reactor.

  1. Step 1

    Get your agent’s address

    Each agent has an address on in.mails.ai. Replies to its mail land there too.

  2. Step 2

    Register a webhook

    Give us an HTTPS address and the events you want. Every delivery is signed.

  3. Step 3

    Handle each event

    Handle it in your app. Or skip the webhook and use the SDK reactor’s stream.

Frequently asked questions

What is an AI agent inbox API?
An AI agent inbox API is a programmatic interface that gives each AI agent its own email address and delivers every inbound message as structured JSON — parsed, threaded, and scored for prompt injection — instead of raw MIME. The agent reads mail over REST, a webhook, or an SSE stream, with no IMAP polling or OAuth to manage.
How does the AI agent inbox API handle prompt injection?
Every inbound message within your plan’s limits is scanned before delivery across six categories — boundary manipulation, system prompt override, data exfiltration, role hijacking, tool invocation, and jailbreaks. The injection_score (0–1) arrives on the event payload so your agent can branch on a number instead of trusting the LLM to notice an attack embedded in the message.
What event types does the inbox API return?
A reply to one of the agent’s sends arrives as a reply.received event. First-contact mail — a message that is not a reply — arrives as a message.received event. When classification is turned on, first-contact mail also carries its detected intent, entities, and urgency. Both event types include the parsed sender, subject, plain-text body, thread id, and SPF/DKIM results.
Can I receive inbound email by webhook, polling, or streaming?
All three. Register a signed HTTPS webhook and get a POST for each event, poll GET /v1/events with filters for batch processing, or hold open the SSE stream at /v1/events/stream for real-time delivery. The same structured payload is delivered through every channel.
Does the AI agent inbox API include threading?
Yes. Replies are linked to their original send by In-Reply-To, so the agent reads an entire conversation from a single thread id. The dashboard shows each thread as one row, and the API lets you page through a thread’s messages in order.
What does the AI agent inbox API cost?
Free covers 3,000 emails and 3,000 inbound replies a month with one agent — no credit card required. Pro is $20/month for 50,000 emails and 50,000 inbound replies across five agents. Scale is $99/month for 250,000 emails, 500,000 inbound replies, and unlimited agents.

Give your first agent an inbox

Free covers 3,000 emails and 3,000 inbound replies a month, with no card. Upgrade when your agents get busy.

Get your API key