Mailboxes

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.

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.

GET/v1/mailboxes#

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

Authentication: send your API key as a bearer token. See Authentication.

Query parameters#

Response#

Status 200 OK.

{
  "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, HTTP 401: The API key is missing, malformed, revoked or unknown.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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.

Request body#

Send a JSON object.

Example body:

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

Response#

Status 201 Created.

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

Errors#

• unauthorized, HTTP 401: The API key is missing, malformed, revoked or unknown.
• 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, HTTP 413: The body is over 256 KiB.
• plan_limit, HTTP 402: The plan's mailbox limit is reached.
• subscription_required, HTTP 402: The account has no active plan, so it cannot create mailboxes. Nothing was created.
• unknown_product, HTTP 404: No such sending domain on this account.
• provider_unavailable, HTTP 503: The mailbox provider could not be reached.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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"
}'