---
title: "API reference: Mailboxes"
url: "https://coldmeetings.com/docs/api/mailboxes.md"
canonical_url: "https://coldmeetings.com/docs/api/mailboxes"
last_updated: "2026-10-23"
type: "reference"
summary: "List mailboxes with their ramp up send capacity and create a mailbox on a sending domain with the ColdMeetings API."
related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"]
---

# API reference: Mailboxes

> **For AI agents:** the complete index of ColdMeetings pages is [llms.txt](https://coldmeetings.com/llms.txt). Every page is also served as markdown at its URL plus .md.

List mailboxes with their ramp up send capacity and create a mailbox on a sending domain with the ColdMeetings API.

Mailboxes on your sending domains, and how many messages they may send today. New mailboxes ramp up with real low volume sends.

Base URL: `YOUR_API_BASE_URL`. Every request and response is JSON. Errors use [one envelope](https://coldmeetings.com/docs/errors.md).

| Operation | What it does |
| --- | --- |
| [`GET /v1/mailboxes`](#get-v1mailboxes) | List mailboxes and today's ramp-up send capacity. |
| [`POST /v1/mailboxes`](#post-v1mailboxes) | Create a mailbox on a sending domain. 503 until configured. |

## Ramp up schedule

A mailbox may send only as many messages a day as its age allows, and the cap rises as the mailbox ages. New mailboxes send real, low volume mail to real prospects. There is no warmup pool and no simulated engagement.

| Mailbox age | Messages a day |
| --- | --- |
| 0 to 6 days | 5 |
| 7 to 13 days | 10 |
| 14 to 20 days | 20 |
| 21 to 27 days | 30 |
| 28 days and older | 40 |

## GET /v1/mailboxes

List mailboxes and today's ramp-up send capacity.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

### Query parameters

| Name | Type | Notes |
| --- | --- | --- |
| `limit` | integer | Rows per page, 1 to 100. More than 100 is held to 100. |
| `cursor` | string | The next_cursor of the previous page, sent back unchanged to the same route. Leave it out for the first page. A cursor that was edited or came from another route is refused. |

### Response

Status 200 OK.

```json
{
  "daily_send_capacity": 5,
  "capacity_note": "Sum of each verified mailbox's ramp-up cap. Real sends only; there is no warmup pool.",
  "mailboxes": [
    {
      "id": "mbx_7Rw3ZbN1pEs9fKd2LmQxVt",
      "email": "maya@acme-mail.example",
      "domain_id": "dom_4kT9xQp2Wm7ZsLr1VbN8cE",
      "created_at": "2026-10-17T12:00:00.000Z",
      "age_days": 3
    }
  ],
  "next_cursor": null
}
```

- `daily_send_capacity` counts only mailboxes on a domain whose SPF, DKIM and DMARC checks pass. It adds up each mailbox's cap for its age.
- New mailboxes ramp up with real low volume sends to real prospects. There is no warmup pool and no simulated engagement.
- Oldest first, 20 a page. Send `limit` (1 to 100) for more, and send `next_cursor` back as `cursor` for the next page; `next_cursor` is `null` on the last page.

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl YOUR_API_BASE_URL/v1/mailboxes \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY"
```

## POST /v1/mailboxes

Create a mailbox on a sending domain. 503 until configured.

The mailbox address is `local_part@domain`. A password is generated and discarded: it is never stored or shown.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

> This operation answers 503 `provider_unavailable` when its outside service cannot be reached. The mailbox provider could not be reached. Nothing is simulated and nothing is charged.

### Request body

Send a JSON object.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain_id` | string | Yes | Id of a registered sending domain, such as `dom_4kT9xQp2Wm7ZsLr1VbN8cE`. |
| `local_part` | string | Yes | Pattern `^[a-z0-9][a-z0-9._-]{0,62}$`. |
| `given_name` | string | Yes | Up to 60 characters. |
| `family_name` | string | Yes | Up to 60 characters. |

Example body:

```json
{
  "domain_id": "dom_4kT9xQp2Wm7ZsLr1VbN8cE",
  "local_part": "maya",
  "given_name": "Maya",
  "family_name": "Ortiz"
}
```

### Response

Status 201 Created.

```json
{
  "id": "mbx_7Rw3ZbN1pEs9fKd2LmQxVt",
  "email": "maya@acme-mail.example"
}
```

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`invalid_input`](https://coldmeetings.com/docs/errors.md#invalid_input), HTTP 400: The address already exists. A body that is empty, is not JSON or fails validation also answers this, and the message names the field.
- [`payload_too_large`](https://coldmeetings.com/docs/errors.md#payload_too_large), HTTP 413: The body is over 256 KiB.
- [`plan_limit`](https://coldmeetings.com/docs/errors.md#plan_limit), HTTP 402: The plan's mailbox limit is reached.
- [`subscription_required`](https://coldmeetings.com/docs/errors.md#subscription_required), HTTP 402: The account has no active plan, so it cannot create mailboxes. Nothing was created.
- [`unknown_product`](https://coldmeetings.com/docs/errors.md#unknown_product), HTTP 404: No such sending domain on this account.
- [`provider_unavailable`](https://coldmeetings.com/docs/errors.md#provider_unavailable), HTTP 503: The mailbox provider could not be reached.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl -X POST YOUR_API_BASE_URL/v1/mailboxes \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "domain_id": "dom_4kT9xQp2Wm7ZsLr1VbN8cE",
  "local_part": "maya",
  "given_name": "Maya",
  "family_name": "Ortiz"
}'
```

## Related

- [API reference](https://coldmeetings.com/docs/api.md)
- [Errors](https://coldmeetings.com/docs/errors.md)