# 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": "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`](https://robotomail.com/docs/api/auth#endpoint) for the account-wide total and limit.


## 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 email domain. Custom domains require the paid plan and a [verified domain](https://robotomail.com/docs/concepts/domains).

### 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 /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 3 active mailboxes


## 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 }
```


---

Previous: [API Keys](https://robotomail.com/docs/api/api-keys.md) | Next: [Messages](https://robotomail.com/docs/api/messages.md)