---
title: "Request mailboxes Coldrig sets up on an already-active BYO domain."
method: POST
path: "/byo-domains/{id}/managed-mailboxes"
tags: ["byo-domains"]
---

# Request mailboxes Coldrig sets up on an already-active BYO domain.

`POST /byo-domains/{id}/managed-mailboxes`

## Request

- Base URL: `https://api.coldrig.dev`
- URL: `https://api.coldrig.dev/byo-domains/{id}/managed-mailboxes`
- Auth: HTTP bearer

The primary build target: the vendor sets up new mailboxes under the customer's own domain, reusing the same setup path as the lookalike-domain flow. Requires the domain to already be active (past DNS verification). These are mailboxes Coldrig sets up, so they count toward the standard per-mailbox quantity billing ($5 a month for each mailbox past the first 3); pass `quoteOnly: true` to preview the new count + projected monthly before setup.

## Path parameters

- `id` string, required

## Request body

- RequestManagedByoMailboxesInput
  - `count` integer, required: At most 5; on a live account, a domain with no managed mailboxes needs 3-5.
  - `personaSlug` string: Optional; defaults to a slug of the domain.
  - `quoteOnly` boolean: Quote-before-add — true previews the new count + projected monthly without setup.

## Response `201`

Mailboxes set up.

- ManagedMailboxesResult
  - `mailboxEmails` string[], required
  - `billing` MailboxBilling, required: Billing projection returned on every mailbox add/remove (no silent capacity addition). `provisionedAfter` is the live mailbox count AFTER the call — reality, not the ask (a capacity-limited partial or a quoteOnly preview both report the true resulting count).
    - `provisionedAfter` integer, required: Live set-up mailbox count after this operation.
    - `projectedMonthlyCents` integer, required: Projected monthly: $49 a month covers the first 3 mailboxes, then $5 a month for each extra mailbox (3-mailbox minimum) — folding any checkout discount.
    - `formula` string, required
    - `domainEnding` object: Only on a quoteOnly preview of an order over 10 mailboxes in the account's first billing month that buys new domains, when the platform's .co switch is on: they will end in .co unless the real call sends `dotComDomains: true`.
      - `ending` 'co', required
      - `newDomains` integer, required: New domains this order buys.
      - `feeCentsEach` integer, required: The one-time fee per .com domain bought, in cents, added to the next bill.
      - `text` string, required: The same
    - `prepay` object: Only on a quoteOnly preview of an order making more than 4 new domains in your first billing month, when the platform's prepaid-month switch is on: the real call must send `prepaySecondMonth: true` (else 400 `prepay_required`, nothing bought); month 2 is then charged right after the mailboxes are set up, at most `cents`.
      - `months` 2, required: The month paid up front is the second one.
      - `cents` integer, required: Month 2 at this order's mailbox count.
      - `text` string, required: The same

## Other responses

- `202`: A large order: it would bring the account more than 20 mailboxes past what its last confirmed payment covered, so nothing was set up or charged. Returns { provisioning: "payment_pending", billing, payment }. A person with the card pays at `payment.url`; then repeat this same request.
- `400`: Request body failed schema validation.
- `401`: Missing, invalid, or inactive bearer token.
- `404`: Resource not found, or not owned by the authenticated account.
- `409`: Setup is paused while Coldrig support checks recent purchases on this account. Not a failure, and nothing was charged for this step; sending, existing mailboxes and the plan are not affected. `reason` names why. Once support finishes, repeating the same request (same idempotency key) completes it.
- `502`: A real vendor call failed (domain registrar or mailbox provider) — materially different from a bug in this service. `step` names the vendor operation that failed when derivable; `retryable` is the adapter's own grade, so a caller can back off instead of guessing. THE GRADE IS TWO INDEPENDENT QUESTIONS. `retryable` says whether an immediate re-attempt can succeed on its own. `operatorActionable` says whether Coldrig's team can clear the refusal — funding a provider account, rotating a credential, un-suspending a workspace — after which your SAME request, with the same idempotency key, completes. When it is true the `code` is `vendor_operator_blocked`: do not change your inputs and do not give up, because nothing about the request is wrong. When both are false the refusal is yours to fix or to escalate.
- `503`: A required vendor integration is not yet enabled for this account. Nothing was charged. This condition has no automatic notification to Coldrig's team behind it, so the response says so and points at contact_operator rather than implying a human is already on it.

## Changes

- **2026-10-19** `242a462d82c4`: 3 info
  - added the optional property `billing/domainEnding` to the response with the `201` status
  - added the optional property `billing/prepay` to the response with the `201` status
  - added the success response with the status `202`

[Operation history](https://skmtc.dev/coldrig/apis/agent-cold-email-api/changes/byo-domains/:id/managed-mailboxes/post.md)

---

[API](https://skmtc.dev/coldrig/apis/agent-cold-email-api.md) · [All operations](https://skmtc.dev/coldrig/apis/agent-cold-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coldrig/apis/agent-cold-email-api/revisions/242a462d82c4?raw)