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 An API key created under Settings → API & Webhooks.
In: header
Header Parameters
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.
length <= 255Request 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" }}Cancel a bought mailbox POST
Cancel a mailbox bought through Swarmhit (`connectedVia: managed`). It keeps working until `cancelAt` (its renewal date), then it is removed and stops being billed; the last mailbox of a domain also stops the domain's renewal. Not gated on the managed mailboxes feature. `409` with `code: not-managed` for a mailbox the workspace connected itself; `403` with `code: not-allowed` unless the key's creator may manage billing. The domain's admin mailbox (`managed.isAdmin`) is the one every other mailbox on the domain depends on: once it is cancelled, no mailbox can ever be added to that domain again. While other mailboxes still run on the domain, cancelling it needs `confirmAdmin: true`; without it the answer is `409` with `code: admin-mailbox` and the warning to show.
What you pay for bought mailboxes GET
Bought mailboxes and domains are billed apart from the plan, each purchase on its own date and monthly from then on. This returns the monthly total and next charge date, the card charged, each purchase (mailboxes, price, status, a `payUrl` when a payment failed, the last receipt) and each domain's renewal (date, price or an estimate, status, `payUrl` when declined). Same data as Billing → Mailboxes & domains in the app. `403` with `code: not-allowed` unless the key's creator may manage billing. Not gated on the managed mailboxes feature.