Mailbox in one call

A live mailbox is one call away. Pick the surface that matches where your agent runs — the request shape is identical underneath.

Get a key

You authenticate with a scoped agent key (pk_agent_…). You get one by redeeming an enrollment key (pk_enroll_…) that a human or org-admin minted for you. The enrollment key can create up to N mailboxes and nothing else — see Authentication & keys.

export POSTERN_API_KEY="pk_agent_7Hq2…"          # your scoped agent key
export POSTERN_API_BASE_URL="https://api.agents.mszazu.com"

Create a mailbox

curl -sS -X POST "$POSTERN_API_BASE_URL/v1/inboxes" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Support Bot" }'

Response:

{
  "id": "inbox_3kP9wQ",
  "address": "agent7@x4p.mszazu.com",
  "display_name": "Support Bot",
  "domain": "x4p.mszazu.com",
  "status": "live",
  "created_at": "2026-06-12T18:04:11Z"
}

Omit username and domain and Postern mints an instant address on a pre-verified, pre-warmed shared mszazu.com subdomain — no DNS, no waiting.

npm install @postern/sdk

import { Postern } from "@postern/sdk";

const postern = new Postern({ apiKey: process.env.POSTERN_API_KEY! });

// One call. A real, send-and-receive-capable mailbox.
const inbox = await postern.inboxes.create({ display_name: "Support Bot" });

console.log(inbox.address); // agent7@x4p.mszazu.com
console.log(inbox.status);  // "live"

inboxes.create() returns an InboxHandle bound to that one address, so the rest of your agent code reads naturally: inbox.send(...), inbox.messages(), inbox.waitForEmail(...), inbox.delete().

Point your MCP host at the Postern server (see Client configuration), then ask the agent to call create_inbox:

{
  "name": "create_inbox",
  "arguments": { "display_name": "Support Bot" }
}

{
  "id": "inbox_3kP9wQ",
  "address": "agent7@x4p.mszazu.com",
  "status": "live"
}

Omit username/domain for an instant agent@<label>.mszazu.com address.

Send from it

The mailbox is registered as an authenticated ACS sender at creation time, so mail from it is SPF + DKIM aligned and doesn’t bounce.

curl -sS -X POST "$POSTERN_API_BASE_URL/v1/inboxes/agent7@x4p.mszazu.com/send" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ops@acme.test",
    "subject": "agent online",
    "text": "Reporting in."
  }'

await inbox.send({
  to: "ops@acme.test",
  subject: "agent online",
  text: "Reporting in.",
});

{
  "name": "send_email",
  "arguments": {
    "address": "agent7@x4p.mszazu.com",
    "to": "ops@acme.test",
    "subject": "agent online",
    "text": "Reporting in."
  }
}

Read what comes back

curl -sS "$POSTERN_API_BASE_URL/v1/inboxes/agent7@x4p.mszazu.com/messages?direction=inbound" \
  -H "Authorization: Bearer $POSTERN_API_KEY"

const { data: messages } = await inbox.messages({ direction: "inbound" });
const { data: threads } = await inbox.threads();

{ "name": "read_messages", "arguments": { "address": "agent7@x4p.mszazu.com", "unread_only": true } }

The whole flow

Redeem an enrollment key for a scoped agent key. POST /v1/enroll
Create a mailbox — instant on a shared subdomain. POST /v1/inboxes
Send from it, ACS-authenticated. POST /v1/inboxes/{addr}/send
Receive via messages, webhooks, or block on wait_for_email. POST /v1/inboxes/{addr}/wait
Delete when the task is done — WildDuck account + ACS sender torn down. DELETE /v1/inboxes/{addr}

wait_for_email — the OTP / verification flow.
Authentication & keys — enrollment keys, agent keys, scopes.
API reference — the full /v1 contract.