developers · api-first

Build on agent mail
in three calls.

A hosted HTTP API that describes itself: point your agent at /llms.txt, follow it to /openapi.json, and 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
$ curl -X POST https://postillion.ai/v1/inboxes \
   -H "Authorization: Bearer $POSTILLION_API_KEY" \
   -d '{ "name": "Triage", "team": "support" }'

{
  "id": "ibx_a1f9",
  "canonical_address": "triage-q7k2m9@agents.northwind.email",
  "status": "active",
  "signing": { dkim: "ok", selector: "pbx-2026a" }
}

Quickstart

From zero to a sent message.

Get a key & discover the API

Generate a key in the console, then let your agent read the live contract — no install.

$ export POSTILLION_API_KEY=sk_live_a1…7be
# the running server describes itself
$ curl https://postillion.ai/llms.txt
$ curl https://postillion.ai/openapi.json

Create a durable inbox

One POST mints a canonical address + DKIM selector — no tenant DNS.

$ curl -X POST https://postillion.ai/v1/inboxes \
   -H "Authorization: Bearer $POSTILLION_API_KEY" \
   -d '{ "name": "Triage", "team": "support" }'

// → "canonical_address": "triage-q7k2m9@agents.northwind.email"

Send & receive

Send as the canonical address; list incoming without marking read.

$ curl -X POST https://postillion.ai/v1/inboxes/ibx_a1f9/send \
   -H "Authorization: Bearer $POSTILLION_API_KEY" \
   -d '{ "to": "dana@brightwave.io", "subject": "Re: invoice #4021", "text": "Resolved." }'

$ curl https://postillion.ai/v1/inboxes/ibx_a1f9/messages \
   -H "Authorization: Bearer $POSTILLION_API_KEY"
// metadata only — listing never marks read

Surfaces

One API today, more on the way.

The hosted HTTP API is live now and self-describing. Typed SDKs, a hosted MCP endpoint, and a packaged CLI are on the roadmap — same auth, same audit when they land.

HTTP API

The live surface today. A Bearer-authenticated REST API that describes itself: fetch /llms.txt and /openapi.json straight off the running server, then call it with any HTTP client.

available nowcurl · any language

Typed SDKs

Typed clients for TypeScript and Python, generated from the same OpenAPI document the API serves today. Until they ship, the spec is the contract — generate a client or call the API directly.

TypeScript · Python — coming soon

MCP server

Inbox, message, thread, draft, and attachment tools exposed over the Model Context Protocol so an agent calls mail directly. A hosted endpoint is on the roadmap.

coming soon

CLI

Provision, inspect, and debug from your shell or CI — check DNS, tail events, and explain delivery decisions inline. A packaged CLI is on the roadmap; today the API does all of this.

coming soon

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/content marks read

POST /v1/messages/:id/reply reply · reply-all

POST /v1/inboxes/:id/send send mail

GET /v1/{scope}/:id/authorization/communication-controls list controls

Events

Event stream,
ReBAC-filtered.

An append-only stream of delivery, policy, auth, DNS, and lifecycle events — readable through the API and console, ReBAC-filtered so you only ever see events your credential is authorized to see. Outbound webhook delivery to your own endpoint is on the roadmap.

event stream — live ReBAC-filtered outbound webhooks — soon

event payload (shape preview)

{
  "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