Provisioning API · Internal testing only
Connect mailboxes to a sequencer
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/inboxes/upload';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"workspace_id":"wsp_01k5n2rf8bd3xa9e7m4jt6vq5h","domain_ids":["dom_01k5nb3wz7q2hj8vd4rt6ye9ma"],"strategy":{"mailboxes_per_domain":50,"warmup_days":10,"outreach_per_day":2}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.builders.ac/api/provisioning/v1alpha1/inboxes/upload \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h", "domain_ids": [ "dom_01k5nb3wz7q2hj8vd4rt6ye9ma" ], "strategy": { "mailboxes_per_domain": 50, "warmup_days": 10, "outreach_per_day": 2 } }'Connects every created Inbox on the named Domains that is not yet connected to the sequencer those Domains are bound to (PUT /domains/{dom}/sequencer). All Domains must belong to the Workspace and share one sequencer account and workspace; the Inbox set is fixed when the request is accepted and is the Operation’s target. Available only to accounts entitled to Mailbox Upload (422 mailbox_upload_unavailable otherwise). A succeeded Operation connected every Inbox. When only some were connected the Operation fails with inbox_upload_partial (retryable; a retry skips the Inboxes already connected), and with inbox_upload_failed when none were; uploaded and failed say how many, and each Inbox’s own sequencer.state says which.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Domains in the Workspace whose Inboxes to connect. Every one must be bound to the same sequencer account and workspace.
Sending strategy to apply to the Workspace before the upload runs. Omit it to keep the current values; supply only the keys you want changed. Refused with 422 when the Domains belong to a Sender managed outside this API.
object
Mailboxes each Domain is sized for. Default 50.
Days of warmup before full sending volume. Default 15.
Outreach emails per Inbox per day once warm. Default 2.
Responses
Section titled “Responses”Inbox upload accepted.
object
Canonical lowercase TypeID.
Canonical lowercase TypeID.
Nearest ancestor public Operation which caused this child Operation. Omitted on root Operations.
object
uploaded counts target Inboxes the sequencer has confirmed. failed is the remainder once the Operation is done; a succeeded Operation may still report uploaded below requested when the sequencer skipped some Inboxes.
object
Cancellation was requested. It is honoured only at a safe boundary, so keep polling state and done to learn whether it took effect.
Next date by which meaningful progress should be visible.
Public completion SLA for this Operation.
Example
{ "id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw", "object": "operation", "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h", "parent_operation_id": "op_01k5nf4b8yt3qd7vm2ae9rz6hx", "type": "inbox.upload", "state": "pending", "done": false, "target": { "object": "inbox_collection", "ids": [ "inb_01k5nc9te4vr7bd2hq8ym3xz6a" ] }, "metadata": { "provider": "smartlead", "sequencer_workspace": "Northwind Outbound", "requested": 3, "uploaded": 3, "failed": 0 }, "created_at": "2026-04-15T09:15:04Z", "update_by_date": "2026-04-15T09:45:04Z", "completion_by_date": "2026-04-15T10:15:04Z"}Headers
Section titled “Headers”Canonical URL of the Operation.
Present with value true only for a stored exact replay.
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.
Idempotency key required. The example shows idempotency_key_required.
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/idempotency_key_required", "title": "Idempotency key required", "status": 400, "detail": "This request requires a valid Idempotency-Key header.", "code": "idempotency_key_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.
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.
Inbox upload was refused atomically. The problem code identifies the eligibility, overlapping-operation, workspace, or idempotency boundary.
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
The Operation holding the resource. Null when the blocking run is a dashboard workflow, which has no public Operation; absent on chapters that do not report it.
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
No inboxes to upload
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/no_inboxes_to_upload", "title": "No inboxes to upload", "status": 409, "detail": "Every created inbox on these domains is already connected to the sequencer. Create more inboxes, or wait for pending ones to finish provisioning, then retry with a new Idempotency-Key.", "code": "no_inboxes_to_upload", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Resource operation in progress
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/resource_operation_in_progress", "title": "Resource operation in progress", "status": 409, "detail": "Wait for the current operation to finish, then retry with a new Idempotency-Key.", "code": "resource_operation_in_progress", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "operation_id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw"}Workspace archived
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/workspace_archived", "title": "Workspace archived", "status": 409, "detail": "Unarchive this workspace before creating resources in it.", "code": "workspace_archived", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Request already in progress
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_in_progress", "title": "Request already in progress", "status": 409, "detail": "A request using this idempotency key is still in progress.", "code": "idempotency_in_progress", "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.
The request is well-formed but cannot be acted on: the account is not entitled to Mailbox Upload, some Domains have no sequencer binding (domain_ids lists them), the Domains are bound to different targets, or a field is invalid.
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
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"}Domains have no sequencer
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/domains_not_bound", "title": "Domains have no sequencer", "status": 422, "detail": "Some of these domains are not bound to a sequencer account; `domain_ids` lists them. Bind each one with PUT /domains/{dom}/sequencer, then retry.", "code": "domains_not_bound", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "domain_ids": [ "dom_01k5nb3wz7q2hj8vd4rt6ye9ma" ]}Sequencer targets differ
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/sequencer_targets_mixed", "title": "Sequencer targets differ", "status": 422, "detail": "These domains are bound to different sequencer accounts or workspaces. One upload connects to one target: split the request by target and upload each separately.", "code": "sequencer_targets_mixed", "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.