Mailboxes API

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

{
  "mailboxes": [
    {
      "id": "a1b2c3d4-5678-4def-abcd-111111111111",
      "address": "hello",
      "fullAddress": "myagent@robotomail.co",
      "displayName": "My Agent",
      "dailySendCount": 5,
      "dailySendLimit": 100,
      "monthlySendCount": 120,
      "monthlySendLimit": 5000,
      "receivedThisMonth": 42,
      "status": "ACTIVE",
      "createdAt": "2026-03-11T00:00:00.000Z"
    }
  ]
}

receivedThisMonth is the per-mailbox inbound count for the current calendar month (UTC). The account-level monthly cap is summed across all mailboxes — see GET /v1/account for the account-wide total and limit.

Create a new mailbox. Requires full-access key.

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

Errors

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

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

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

Errors

• 403 — Free plan: cannot reactivate custom-domain mailbox or exceed 3 active mailboxes

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

{ "deleted": true }