Order mailboxes on several domains
Orders mailboxes on up to 50 domains in one call, buying the ones sent with buy: true first (for a year, to the customer's registrant or your default one). The wallet is checked for everything up front, so a short balance changes nothing. Each domain then succeeds or fails on its own: results says which, and a failed one can be sent again alone. A domain still being registered comes back awaiting_domain, its mailboxes paid for and set up once the registration finishes. Send an Idempotency-Key header so a retry never orders twice.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
Idempotency-Key?stringA value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again.
8 <= length <= 200application/json- body
customerId*stringWho every domain and mailbox is for
domains*array<>1 <= items <= 50Created
application/json- response
Created
results*array<>curl -X POST "https://example.com/v1/mailboxes/bulk" \ -H "Idempotency-Key: 2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "domains": [ { "domain": "northwind-mail.com", "mailboxes": [ { "username": "jo", "firstName": "Jo", "lastName": "Bloggs" } ] } ] }'{ "results": [ { "domain": "northwind-mail.com", "ok": true, "registeredDomainId": "dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "mailboxDomain": { "id": "mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "domain": "northwind-mail.com", "status": "awaiting_domain", "source": "resellerhq", "domainId": "dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "nameserversManaged": true, "nameservers": [ "ns1.example-dns.net" ], "failure": { "code": "DOMAIN_IN_USE_GOOGLE", "message": "Domain is already in use in Google Workspace." }, "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "unitPrice": 450, "customerPrice": 450, "periodEndsAt": "2026-10-07T11:04:31.000Z", "unpaidSince": "2026-10-07T11:04:31.000Z", "deletesAt": "2026-10-07T11:04:31.000Z", "forwarding": { "url": "https://northwind.com", "captcha": true }, "dmarc": { "reportingEmail": "string", "policy": "none", "subdomainPolicy": "none", "percentage": 0 }, "actor": { "kind": "user", "label": "string" }, "createdAt": "2026-10-07T11:04:31.000Z" }, "data": [ { "id": "mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "mailboxDomainId": "mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "email": "[email protected]", "username": "jo", "firstName": "Jo", "lastName": "Bloggs", "profilePictureUrl": "string", "isAdmin": true, "status": "queued", "setupStage": "configuring_dns", "failure": { "code": "DOMAIN_IN_USE_GOOGLE", "message": "Domain is already in use in Google Workspace." }, "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "activatedAt": "2026-10-07T11:04:31.000Z", "actor": { "kind": "user", "label": "string" }, "createdAt": "2026-10-07T11:04:31.000Z" } ], "error": { "code": "DOMAIN_IN_USE_GOOGLE", "message": "Domain is already in use in Google Workspace." } } ]}