mails.ai

The inbound email API.

When someone replies to your agent, the API delivers a structured event — not a MIME blob — with its injection score and sender reputation.

Get startedDocumentation

Inbound email API

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.

Read the API referenceGet your API key
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: conversations grouped by agent, with their subject and participants

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 the API works

Structured events, not raw MIME

Cloudflare Email Routing hands each message to our edge worker, the API parses it, 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 the inbound API

Three steps to inbound email 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.

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