developers · api-first

Build on agent mail
in three calls.

One API powers the SDKs, the MCP server, the CLI, and the console. Create an inbox, send a message, read the thread — authenticated, signed, and audited from the first request.

Get your API key → API reference
first request 200 OK 
$ export POSTILLION_API_KEY=sk_live_a1…7be
$ postillion inbox create --name "Triage" --team support

✓ inbox created
  id        ibx_a1f9
  address   triage-q7k2m9@agents.northwind.email
  signing   dkim ok · selector pbx-2026a
  dns       verified
Quickstart

From zero to a sent message.

1
Install & authenticate
Generate a key in the console, then install the client.
# TypeScript
$ npm i postillion
# Python
$ pip install postillion
2
Create a durable inbox
Mints a canonical address + route and signs it.
const pb = new Postillion(process.env.POSTILLION_API_KEY);
const inbox = await pb.inboxes.create({ name: "Triage", team: "support" });
console.log(inbox.canonical_address);
// → triage-q7k2m9@agents.northwind.email
3
Send & receive
Send as the canonical address; list incoming without marking read.
await ab.messages.send({ inbox: inbox.id, to: "dana@brightwave.io",
  subject: "Re: invoice #4021", text: "Resolved." });

const threads = await ab.threads.list({ inbox: inbox.id, unread: true });
// metadata only — listing never marks read
Surfaces

Pick how you call it.

Same API, same auth, same audit. Reach for whichever fits the caller.

SDKs

Typed clients for TypeScript and Python with full coverage of inboxes, messages, threads, drafts, labels, and policy.

npm i postillionpip install postillion

MCP server

A hosted server exposes inbox, message, thread, draft, and attachment tools. Your agent calls mail directly — no console round-trip.

hostedOAuth · per-org

CLI

Provision, inspect, and debug from your shell or CI. Check DNS, tail events, and explain delivery decisions inline.

brew install postillion 
{
  "mcpServers": {
    "postillion": {
      "url": "https://mcp.postillion.ai",
      "auth": "oauth"
    }
  }
}
REST API

Predictable, resource-shaped.

Every resource has list, read, and scoped mutations. Bulk replace requires an expected version; single-entry mutations are idempotent. All mutations are audited.

Full reference →
POST /v1/inboxes create inbox
GET /v1/inboxes list & filter
GET /v1/inboxes/:id/messages metadata only
GET /v1/messages/:id?format=agent marks read
POST /v1/messages/:id/reply reply · reply_all
PUT /v1/inboxes/:id/policy expects etag
GET /v1/events ReBAC-filtered
Realtime

Webhooks & event streams,
ReBAC-filtered.

Subscribe to delivery, policy, auth, DNS, and lifecycle events. Subscriptions only ever deliver events the credential is authorized to see — no leaking across scope.

signed payloads at-least-once replayable
POST /your-endpoint 
{
  "type": "message.delivered",
  "inbox": "ibx_a1f9",
  "decision": "accept",
  "sender": "dana@brightwave.io",
  "auth": "dmarc_aligned",
  "etag": "v18"
}

Your key is one click away.

Free tier includes durable inboxes on a managed domain — no DNS setup required.

Get your API key → Read the docs