JavaScript SDK: swarmhit.mailboxOrders.create(params)
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, domain-admin-cancelled or domain-not-ready, and 404 with code: domain-not-owned.
Authorization
bearerAuth An API key created on the Access tokens page.
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. Read only by the endpoints that list it. A key is scoped to the endpoint and the account (or chat) it acts on, and kept for 24 hours. Only a successful response is stored and replayed: a 4xx frees the key, while a 5xx keeps it (the action may have gone out; retry with a new key). So does a 400 passing on a LinkedIn, WhatsApp or mail provider failure (code provider-unreachable, provider-408 for the provider's own timeout, or provider- and a 5xx status such as provider-502), unless the request provably never reached the provider (its connection never opened): the action may have gone out. A retry with the same key then gets 409 idempotency_failed. The request body is not compared, so a reused key replays the first response even if the body differs.
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
application/json
curl -X POST "https://example.com/mailbox-orders" \ -H "Content-Type: application/json" \ -d '{ "quoteId": "string" }'{ "data": { "id": "string", "workspaceId": "string", "workspaceName": "string", "status": "quoted", "delayed": true, "statusLabel": "string", "createdVia": "app", "hostedLinkId": "string", "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", "emailVerification": { "status": "pending", "deadline": "2019-08-24T14:15:22Z" }, "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" }}Check an own domain now POST
**JavaScript SDK:** [`swarmhit.managedDomains.check(managedDomainId)`](/smart-api/sdk/methods#managedDomains) Look at an own domain again now, e.g. right after changing its nameservers: the next check runs within a minute. Returns the domain as it is now. 409 `not-own-domain` for a domain bought here.
What you pay for bought mailboxes GET
**JavaScript SDK:** [`swarmhit.mailboxBilling.get()`](/smart-api/sdk/methods#mailboxBilling) 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 the **Mailboxes & domains** tab of Settings → Billing in Swarmhit. `403` with `code: not-allowed` unless the key's creator may manage billing. Not gated on the managed mailboxes feature.