API · Inboxes

All inbox endpoints require a scoped agent key. The mailbox {addr} in a path is the full, URL-encoded address (agent7%40x4p.mszazu.com).

POST /v1/inboxes — create

Request

{
  "username": "support",          // optional; omit for a generated local part
  "domain": "x4p.mszazu.com",     // optional; omit for a shared subdomain
  "display_name": "Support Bot",  // optional
  "client_id": "create-12",       // optional; idempotency key
  "inbound_webhook_url": "https://my-agent.example.com/inbound" // optional
}

Field	Type	Notes
username	string?	Local part. Omit for a generated one.
domain	string?	Must be within the key’s allowed_domains. Omit for the default shared subdomain.
display_name	string?	Friendly name on outbound mail.
client_id	string?	Idempotent create — same client_id returns the same mailbox.
inbound_webhook_url	string?	Register an HMAC-signed message.received webhook for this 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 201

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

Counts against the quota

Each successful create increments the enrollment key’s used_count. At max_mailboxes the next create returns 409 enrollment_token_exhausted. Deleting a mailbox does not refund the slot.

x402 paid actions return 402 first

When an org has paid provisioning enabled, POST /v1/inboxes may answer 402 Payment Required with a PAYMENT-REQUIRED challenge. Sign the EIP-3009 authorization and retry. Provisioning is gated on settlement, not on receipt of the signed payload. See x402 test mode.

GET /v1/inboxes — list

curl -sS "$POSTERN_API_BASE_URL/v1/inboxes?limit=20" \
  -H "Authorization: Bearer $POSTERN_API_KEY"

{
  "data": [
    { "id": "inbox_3kP9wQ", "address": "agent7@x4p.mszazu.com", "status": "live" }
  ],
  "next_cursor": null
}

Cursor-paginate by passing next_cursor back as ?cursor=.

GET /v1/inboxes/{addr} — get

curl -sS "$POSTERN_API_BASE_URL/v1/inboxes/agent7%40x4p.mszazu.com" \
  -H "Authorization: Bearer $POSTERN_API_KEY"

DELETE /v1/inboxes/{addr} — delete

Tears down the WildDuck account and the ACS sender, re-checking tenancy. Destructive and not reversible.

curl -sS -X DELETE "$POSTERN_API_BASE_URL/v1/inboxes/agent7%40x4p.mszazu.com" \
  -H "Authorization: Bearer $POSTERN_API_KEY"

{ "id": "inbox_3kP9wQ", "deleted": true }

POST /v1/inboxes/{addr}/send — send

Request

{
  "to": "ops@acme.test",            // string or array
  "subject": "agent online",
  "text": "Reporting in.",          // text and/or html
  "html": "<p>Reporting in.</p>",
  "cc": [],
  "bcc": [],
  "reply_to": "agent7@x4p.mszazu.com",
  "idempotency_key": "send-77"      // optional
}

curl -sS -X POST "$POSTERN_API_BASE_URL/v1/inboxes/agent7%40x4p.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." }'

Response 202

{ "id": "msg_5dRk", "status": "queued", "thread_id": "thread_9aB" }

Send goes out through the authenticated ACS sender — SPF + DKIM aligned. Sends are subject to the mailbox’s ramping daily cap; over the cap returns 429 with Retry-After.

Next

• Messages & threads — reading and replying.
• wait_for_email — blocking receive.
• Errors — status codes and error.codes.