Provisioning API · Internal testing only
Connect a domain to a sequencer
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/domains/dom_01k5nb3wz7q2hj8vd4rt6ye9ma/sequencer';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"provider_account_id":"pra_01jsdqrf91f949ybjwh90xde9g","sequencer_workspace":"Northwind Outbound"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://api.builders.ac/api/provisioning/v1alpha1/domains/dom_01k5nb3wz7q2hj8vd4rt6ye9ma/sequencer \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "provider_account_id": "pra_01jsdqrf91f949ybjwh90xde9g", "sequencer_workspace": "Northwind Outbound" }'Bind the domain to one sequencer account and one workspace on it, and queue every inbox already created on the domain for connection. PUT, so no Idempotency-Key: binding a domain to the sequencer it is already bound to is binding it once. A domain has at most one sequencer, so this replaces any previous binding and re-queues the inboxes against the new one. The domain does not have to be active yet. Answers with the domain, whose sequencer block is the read-back. API-key callers also receive its SMTP password sealed to that key; OAuth MCP callers receive a successful response without smtp_password. Available only to accounts entitled to Mailbox Upload (422 mailbox_upload_unavailable otherwise).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Domain TypeIDs are accepted case-insensitively. Responses use canonical lowercase.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The sequencer account to bind, as GET /provider-accounts lists it.
One of that account’s sequencer_workspaces. A name the account does not know answers 422.
Responses
Section titled “Responses”Updated domain. smtp_password is sealed to the request API Key when present, and omitted for OAuth MCP callers.
object
Where the domain is in its lifecycle. pending is accepted but not started; provisioning is in flight; awaiting_nameservers is waiting for the nameservers this API issued to be delegated at the registrar; active is live; failed needs a retry; deprovisioning and deprovisioned are teardown. Read-only: it moves through the actions, never through PATCH.
Whether we can act on the registration. spaceship: registered through our own registrar account, so nameservers and renewal are ours to change. external: held elsewhere, and the customer must act. unknown: no registrar recorded.
The nameservers this domain must be delegated to. Empty until the connect operation has issued them.
Empty when no health check has ever finished for this domain.
object
failing means the check ran and found a problem; unmeasured means it could not be run, which is not the same thing.
Present on other, carrying the raw internal signal so a new one is never silently invisible.
The automatic redirect served on the domain. Null when no target is set.
object
redirect serves a 301 to the target; clone serves a copy of it on the domain itself.
active: the edge Worker is confirmed serving it. deploying: on its way. failed: the last redirect or clone operation for this domain failed.
The sequencer this domain is bound to, as PUT /domains/{dom}/sequencer left it, with how far its inboxes have got. Null on a domain with no binding.
object
The workspace at the sequencer that inboxes on this domain are connected to.
How many of this domain’s inboxes are connected to that workspace, waiting to be connected, and no longer connected. An inbox that was never linked is in none of the three.
object
Sealed to the request API Key on GET /domains/{dom} and PUT /domains/{dom}/sequencer. Omitted from OAuth MCP sequencer-binding responses; never in a list or on a deprovisioned domain.
object
An ASCII-armored age v1 file. Response values are sealed to the API Key used for the request; request values are sealed to a recipient published by GET /encryption-keys.
Your own id for this domain. Unique per account among live domains, set once and immutable afterwards, released when the domain is deprovisioned.
Example
{ "id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma", "object": "domain", "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h", "name": "northwind-outbound.com", "state": "pending", "registrar": "spaceship", "registered_on": "2026-01-22", "expires_on": "2027-01-22", "nameservers": [ "dara.ns.cloudflare.com", "rex.ns.cloudflare.com" ], "health": [ { "check": "nameservers", "status": "ok" } ], "health_checked_at": "2026-04-16T10:58:12Z", "redirect": { "target_url": "https://www.northwind-labs.com", "mode": "redirect", "state": "deploying", "cloned_at": "2026-04-16T10:44:09Z" }, "sequencer": { "provider_account_id": "pra_01jsdqrf91f949ybjwh90xde9g", "provider": "smartlead", "workspace": "Northwind Outbound", "inboxes": { "uploaded": 3, "pending": 0, "disconnected": 0 } }, "smtp_password": { "ciphertext": "-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHd0pQTGdGMlkxSjhkUzBu\nCg==\n-----END AGE ENCRYPTED FILE-----\n" }, "external_id": "crm-8421", "created_at": "2026-04-15T09:15:04Z", "updated_at": "2026-04-16T11:02:37Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required", "title": "Authentication required", "status": 401, "detail": "Provide an active Provisioning API Key as a Bearer token.", "code": "authentication_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive", "title": "Account inactive", "status": 403, "detail": "This account is inactive.", "code": "account_inactive", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Not found. The example shows not_found.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/not_found", "title": "Not found", "status": 404, "detail": "The requested resource was not found.", "code": "not_found", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
The request is well-formed but cannot be acted on: the account is not entitled to Mailbox Upload, or sequencer_workspace is not a workspace of that account.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
Mailbox Upload unavailable
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/mailbox_upload_unavailable", "title": "Mailbox Upload unavailable", "status": 422, "detail": "Mailbox Upload is not available for this product. Contact your deliverability advisor to discuss.", "code": "mailbox_upload_unavailable", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Rate limit exceeded. The example shows rate_limit_exceeded.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Too many requests were made for this policy.", "code": "rate_limit_exceeded", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "retry_after": "2026-04-15T09:16:04Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Service unavailable. The example shows service_unavailable; this status is also answered with encryption_keys_unavailable, provider_unreachable. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Retry the request later; the service is temporarily unavailable.", "code": "service_unavailable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.