Skip to content
builders.ac

Provisioning API · Internal testing only

createInboxes

POST
/domains/{dom}/inboxes
curl --request POST \
  --url https://api.builders.ac/api/provisioning/v1alpha1/domains/dom_01k5nb3wz7q2hj8vd4rt6ye9ma/inboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "from_personas": [ { "persona_id": "per_01k5n7qd2vb8ye4ka3mzt9rf6x", "count": 1 } ] }'

Atomically adds 1–150 Inboxes to an active Domain. The resulting number of capacity-occupying Inboxes on that Domain must be exactly 50, 75 or 150, so additive top-ups and replacements may request smaller batches. The target Domain and its backing Microsoft 365 tenant each have an effective capacity of 150 Inboxes, and reservation growth must fit the owning Account’s paid mailbox slots. Count, capacity, lifecycle, or overlapping-operation refusals return a typed 409 without reserving any Inbox.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
dom
required
string
>= 30 characters <= 30 characters /^[dD][oO][mM]_[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/

Domain TypeIDs are accepted case-insensitively. Responses use canonical lowercase.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7E]+$/

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”
Media typeapplication/json
One of:
object
from_personas
required

The sum of count across all Persona batches must be between 1 and 150 Inboxes.

Array<object>
>= 1 items <= 150 items
object
persona_id
required
string
>= 30 characters <= 30 characters /^[pP][eE][rR]_[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/
count
required

Number of Inbox identities to generate from this Persona.

integer
>= 1 <= 150
Examples

Generate Inbox addresses from Personas

{
  "from_personas": [
    {
      "persona_id": "per_01k5n7qd2vb8ye4ka3mzt9rf6x",
      "count": 1
    }
  ]
}

Responses

Section titled “Responses”

202

Section titled “202”

Inbox creation accepted.

Media typeapplication/json
object
id
required

Canonical lowercase TypeID.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
object
required
Allowed value: operation
workspace_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^wsp_[0-7][0-9a-hjkmnp-tv-z]{25}$/
parent_operation_id

Nearest ancestor public Operation which caused this child Operation. Omitted on root Operations.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
type
required
Allowed value: inbox.create
state
required
string
Allowed value: pending
done
required
target
required
object
object
required
Allowed value: inbox_collection
ids
required
Array<string>
>= 1 items <= 150 items unique items
metadata
required
object
domain_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^dom_[0-7][0-9a-hjkmnp-tv-z]{25}$/
requested
required
integer
>= 1 <= 150
active
required
integer
<= 150
failed
required
integer
<= 150
retrying
required
integer
<= 150
created_at
required
string format: date-time
started_at
string format: date-time
finished_at
string format: date-time
cancel_requested_at

Cancellation was requested. It is honoured only at a safe boundary, so keep polling state and done to learn whether it took effect.

string format: date-time
update_by_date
required

Next date by which meaningful progress should be visible.

string format: date-time
completion_by_date
required

Public completion SLA for this Operation.

string format: date-time
Example
{
  "id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw",
  "object": "operation",
  "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h",
  "parent_operation_id": "op_01k5nf4b8yt3qd7vm2ae9rz6hx",
  "type": "inbox.create",
  "state": "pending",
  "done": false,
  "target": {
    "object": "inbox_collection",
    "ids": [
      "inb_01k5nc9te4vr7bd2hq8ym3xz6a"
    ]
  },
  "metadata": {
    "domain_id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma",
    "requested": 3,
    "active": 3,
    "failed": 0,
    "retrying": 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”
Location
string

Canonical URL of the Operation.

Idempotency-Replayed
string
Allowed value: true

Present with value true only for a stored exact replay.

x-correlation-id
string

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.

400

Section titled “400”

Idempotency key required. The example shows idempotency_key_required.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
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”
x-correlation-id
string

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.

401

Section titled “401”

Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
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”
x-correlation-id
string

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.

403

Section titled “403”

Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
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”
x-correlation-id
string

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.

404

Section titled “404”

The Domain path or one or more Persona references could not be resolved. errors identifies the affected request locations without revealing whether a resource is missing, deleted, or inaccessible.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
required
object
key
additional properties
Array<string>
type
required
title
required
Allowed value: Not found
status
required
Allowed value: 404
code
required
Allowed value: not_found
retryable
required
detail
required
Allowed value: The requested resource was not found.
errors
required

Identifies the unresolved dom path parameter or every unresolved from_personas.N.persona_id input. Missing, deleted, and inaccessible resources intentionally share the same message.

object
>= 1 properties
key
additional properties
Array<string>
>= 1 items
Examples
Examplenot_found

Not found

{
  "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",
  "errors": {
    "from_personas.0.persona_id": [
      "The Persona was not found or is not accessible."
    ]
  }
}

Headers

Section titled “Headers”
x-correlation-id
string

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.

409

Section titled “409”

Inbox creation was refused atomically. The problem code identifies the lifecycle, capacity, quota, identity, workspace, idempotency, or overlapping-operation boundary.

Media typeapplication/problem+json
One of:
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
type
required
title
required
Allowed value: Domain is not active
status
required
Allowed value: 409
code
required
Allowed value: domain_not_active
retryable
required
detail
required
Allowed value: This action needs a live domain; `state` says where this one is. Wait for it to reach `active` — poll the connect operation — and try again.
state
required

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.

string
Allowed values: pending provisioning awaiting_nameservers active failed deprovisioning deprovisioned
Examples

Domain is not active

{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/domain_not_active",
  "title": "Domain is not active",
  "status": 409,
  "detail": "This action needs a live domain; `state` says where this one is. Wait for it to reach `active` — poll the connect operation — and try again.",
  "code": "domain_not_active",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "state": "pending"
}

Headers

Section titled “Headers”
x-correlation-id
string

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.

422

Section titled “422”

Validation failed. The example shows validation_error; this status is also answered with idempotency_mismatch, invalid_sealed_value, mailbox_upload_unavailable, provider_credentials_invalid, domains_not_bound, sequencer_targets_mixed. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/validation_error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more request fields are invalid.",
  "code": "validation_error",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "errors": {
    "display_name": [
      "The display name must not be blank."
    ]
  }
}

Headers

Section titled “Headers”
x-correlation-id
string

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.

429

Section titled “429”

Rate limit exceeded. The example shows rate_limit_exceeded.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
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”
x-correlation-id
string

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.

503

Section titled “503”

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.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

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.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
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”
x-correlation-id
string

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.