Mailbox orders
POST
/mailbox-orders

Buy the quoted order: charges the workspace's card on file for the quote's dueNowCents, then registers the domains and creates the mailboxes. They arrive connected (no sign-in, connectedVia: managed) and warming unless warmup.enabled is false, usually within hours; follow the order on GET /mailbox-orders/{id} or the mailbox_order.completed / mailbox_order.failed webhooks. Send the quoteId; the order fields are optional and, when sent, must be exactly what was quoted (409, code: quote-mismatch). Buying the same quote again returns the same order with no second charge, and an Idempotency-Key replays the first answer to a retry. 402 with code: no-payment-method or payment-failed when the card cannot be charged; 409 with code: quote-expired, price-changed or domain-unavailable when the quote no longer holds (quote again); 409 with code: payment-pending when the charge is still being confirmed (the order appears in GET /mailbox-orders within minutes if it went through, so do not buy again); 403 with code: not-allowed unless the key's creator may manage billing (owner or admin of the paying workspace). Quoting needs the same right. For existing domains: 409 with code: mailbox-unavailable, domain-full or domain-admin-cancelled, and 404 with code: domain-not-owned.

Authorization

bearerAuth
AuthorizationBearer <token>

An API key created under Settings → API & Webhooks.

In: header

Header Parameters

Idempotency-Key?string

Unique key per action (e.g. a UUID). Reusing it replays the first response instead of sending again, so a retry can't double-send. Recommended on all writes.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/mailbox-orders" \  -H "Content-Type: application/json" \  -d '{    "quoteId": "string"  }'
{  "data": {    "id": "string",    "status": "quoted",    "delayed": true,    "statusLabel": "string",    "createdVia": "app",    "warmup": {      "enabled": true,      "strategy": {        "preset": "conservative",        "startingVolume": 1,        "dailyIncrease": 1,        "targetVolume": 1,        "replyInbox": [          0,          0        ],        "replyPromotions": [          0,          0        ],        "replySpam": 0      }    },    "domains": [      {        "name": "string",        "existing": true,        "platform": "google",        "years": 0,        "redirectUrl": "string",        "status": "pending",        "refusedReason": "string",        "mailboxes": [          {            "email": "string",            "firstName": "string",            "lastName": "string",            "step": "ordered",            "accountId": "string",            "connectedAt": "2019-08-24T14:15:22Z"          }        ]      }    ],    "totals": {      "totalCents": 0,      "currency": "string"    },    "completedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}