Mailboxes API

Create, list, update, and delete mailboxes.

GET /v1/mailboxes

GET/v1/mailboxes

List all mailboxes. Scoped keys only see mailboxes in their scope.

response — 200 OK

{
  "mailboxes": [
    {
      "id": "mbx_abc123",
      "address": "hello",
      "fullAddress": "[email protected]",
      "displayName": "My Agent",
      "dailySendCount": 5,
      "dailySendLimit": 50,
      "status": "ACTIVE",
      "createdAt": "2026-03-11T00:00:00.000Z"
    }
  ]
}

POST /v1/mailboxes

POST/v1/mailboxes

Create a new mailbox. Requires full-access key.

Request body

Name	Type	Description
address*	string	Local part (1-64 chars, alphanumeric/._-)
displayName	string	Friendly name (max 255 chars)
domainId	string	UUID of a verified custom domain

Without domainId, the mailbox uses your platform subdomain. Custom domains require the paid plan and a verified domain.

Errors

400 — Invalid address format or domain not verified
403 — Plan limit exceeded (free: 1 mailbox) or custom domain on free plan
404 — Domain not found

GET /v1/mailboxes/:id

GET/v1/mailboxes/:id

Get a single mailbox by ID. Returns the full mailbox object.

PATCH /v1/mailboxes/:id

PATCH/v1/mailboxes/:id

Update mailbox settings. Works with scoped keys if the mailbox is in scope.

Request body

Name	Type	Description
displayName	string	Updated display name
status	"ACTIVE" \| "PAUSED"	Pause or reactivate the mailbox

Errors

403 — Free plan: cannot reactivate custom-domain mailbox or exceed 1 active mailbox

DELETE /v1/mailboxes/:id

DELETE/v1/mailboxes/:id

Delete a mailbox. Requires full-access key. The underlying Stalwart account is also removed.

response — 200 OK

{ "deleted": true }