# API · Inboxes

{/* // /v1/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

```json
{
  "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. |

```bash frame="terminal"
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`

```json
{
  "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](https://docs.agents.mszazu.com/payments/x402-test-mode/).

## `GET /v1/inboxes` — list

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

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

```bash frame="terminal"
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.

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

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

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

### Request

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

```bash frame="terminal"
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`

```json
{ "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](https://docs.agents.mszazu.com/concepts/deliverability-and-karma/); over the cap returns
`429` with `Retry-After`.

## Next

- [Messages & threads](https://docs.agents.mszazu.com/api/messages-and-threads/) — reading and replying.
- [wait_for_email](https://docs.agents.mszazu.com/api/wait/) — blocking receive.
- [Errors](https://docs.agents.mszazu.com/api/errors/) — status codes and `error.code`s.