> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Add mailboxes
>
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `channels:write` scope (or a broader one that includes it)._
Adds mailboxes to a domain your team already bought. Seats your plan already covers are free; extra seats are charged to the payment card on file.
Send mailboxes with 1 to 5 entries. A domain holds at most 5 mailboxes, existing ones included. isAdmin may be true on one entry only, and only when the domain has no admin mailbox yet.
Take domainId from GET /v3/email-accounts/procurement/domains. Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome.
When the job ends as Failed, its jsonDataResult carries an `errorCode` and a top-level `failureMessage`. Only `procurementOrder.submitFailed` can follow a charge.
| `errorCode` | Meaning |
|---|---|
| `procurementOrder.domainNotFound` | The domain was removed before the order ran. |
| `procurementOrder.validation` | The mailbox configuration was rejected, the domain cannot take mailboxes yet, or the current plan cannot take the order. |
| `procurementOrder.noPaymentMethod` | Extra seats must be bought and no payment card is on file. Add one in billing settings, then retry. |
| `procurementOrder.paymentDeclined` | The payment provider declined the payment. |
| `procurementOrder.paymentActionRequired` | The saved payment method needs interactive authentication. Complete it in the app, then retry. |
| `procurementOrder.temporarilyUnavailable` | A transient failure. Retry — unless failureMessage says the order may have been placed; then contact support first. |
| `procurementOrder.unknown` | The order could not be reliably priced. Retry, or contact support. |
| `procurementOrder.submitFailed` | The order was submitted, and paid when extra seats were needed, but could not be confirmed with the provider. Contact support before ordering again. |
## OpenAPI
````yaml /api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/mailboxes/purchase
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: Contacts
description: Manage individual contacts
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Accounts
description: Manage accounts (companies/organizations)
- name: Account Lists
description: Manage account lists and account membership
- name: Custom Fields
description: Manage custom contact fields
- name: Prompt Actions
description: Save reusable AI prompts and run them on contacts to fill custom fields
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Sequences
description: Manage email automation sequences
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Email Templates
description: Manage email templates and template folders
- name: Voices
description: Manage cloned voices used for AI voice message steps
- name: Schedules
description: Manage email send schedules and timing
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads — list/filter, read state, replies, category
assignment, and meeting-intent flagging
- name: Inbox Categories
description: Manage per-team inbox thread categories and assign threads to them
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Tasks
description: Manage tasks and to-do items
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, generated step types, and playbook/knowledge-base connections
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI Prompts
description: >-
Manage the AI prompts used to configure sequence steps, and preview the
output a prompt produces
- name: AI SDR Learnings
description: >-
Manage the standing rules that shape how the AI writes — list, read,
create, partially update and delete AI learnings
- name: Registration
description: Register the contact that domain purchases are filed under
- name: Domains
description: Find domains available to buy for outreach
- name: Purchased Domains
description: >-
List the domains your team bought, with their subscription, setup and
renewal state
- name: Mailboxes
description: Add mailboxes to domains your team already bought, priced before you order
- name: User Account
description: Account information and authentication verification
- name: Settings
description: Manage team and user settings
- name: Billing
description: Subscription details and monthly active contacts usage
- name: Rate Limits
description: Your API rate limits and current usage
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
paths:
/v3/email-accounts/procurement/domains/{domainId}/mailboxes/purchase:
post:
tags:
- Mailboxes
summary: Add mailboxes
description: >-
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `channels:write` scope (or a broader one that
includes it)._
Adds mailboxes to a domain your team already bought. Seats your plan
already covers are free; extra seats are charged to the payment card on
file.
Send mailboxes with 1 to 5 entries. A domain holds at most 5 mailboxes,
existing ones included. isAdmin may be true on one entry only, and only
when the domain has no admin mailbox yet.
Take domainId from GET /v3/email-accounts/procurement/domains. Returns a
jobId — poll GET /v3/background-jobs/{jobId} for the outcome.
When the job ends as Failed, its jsonDataResult carries an `errorCode`
and a top-level `failureMessage`. Only `procurementOrder.submitFailed`
can follow a charge.
| `errorCode` | Meaning |
|---|---|
| `procurementOrder.domainNotFound` | The domain was removed before the
order ran. |
| `procurementOrder.validation` | The mailbox configuration was
rejected, the domain cannot take mailboxes yet, or the current plan
cannot take the order. |
| `procurementOrder.noPaymentMethod` | Extra seats must be bought and no
payment card is on file. Add one in billing settings, then retry. |
| `procurementOrder.paymentDeclined` | The payment provider declined the
payment. |
| `procurementOrder.paymentActionRequired` | The saved payment method
needs interactive authentication. Complete it in the app, then retry. |
| `procurementOrder.temporarilyUnavailable` | A transient failure. Retry
— unless failureMessage says the order may have been placed; then
contact support first. |
| `procurementOrder.unknown` | The order could not be reliably priced.
Retry, or contact support. |
| `procurementOrder.submitFailed` | The order was submitted, and paid
when extra seats were needed, but could not be confirmed with the
provider. Contact support before ordering again. |
operationId: AddMailboxesToDomain
parameters:
- name: domainId
in: path
required: true
description: ID of a domain your team bought
schema:
type: integer
format: int64
minimum: 1
example: 4182
requestBody:
required: true
content:
application/json:
schema:
type: object
title: AddMailboxesToDomainRequest
properties:
mailboxes:
type: array
minItems: 1
maxItems: 5
description: >-
Mailboxes to create on the domain. Usernames must be unique
within the request, and at most one entry may set isAdmin to
true.
items:
type: object
title: OrderMailbox
description: >-
One mailbox to create on a domain your team already
bought.
properties:
username:
type: string
maxLength: 64
description: >-
Local part of the mailbox address. Latin letters,
numbers, dots, underscores and hyphens only, with no
leading, trailing or double dot. Must not already
exist on the domain.
firstName:
type: string
maxLength: 60
description: >-
Latin letters, digits, hyphens, periods and
apostrophes only
lastName:
type: string
maxLength: 60
description: >-
Latin letters, digits, hyphens, periods and
apostrophes only
needToWarmUp:
type: boolean
default: false
description: Enrol the mailbox in warm-up once it is created
isAdmin:
type: boolean
default: false
description: >-
Marks the mailbox as the domain administrator. Allowed
only when the domain has no admin mailbox yet.
ownerUserId:
type: integer
minimum: 1
description: >-
Team member who will own the resulting email account.
Defaults to the caller.
avatarUrl:
type: string
maxLength: 500
description: HTTP or HTTPS URL of the mailbox profile picture
required:
- username
- firstName
- lastName
required:
- mailboxes
example:
mailboxes:
- username: john.doe
firstName: John
lastName: Doe
needToWarmUp: true
- username: jane.roe
firstName: Jane
lastName: Roe
ownerUserId: 42
responses:
'202':
description: Order accepted; poll the returned job for the outcome
headers:
Location:
description: Relative URL of the background job, v3/background-jobs/{jobId}
schema:
type: string
content:
application/json:
schema:
type: object
title: ProcurementOrderScheduleResponse
properties:
jobId:
type: string
format: uuid
description: Poll GET /v3/background-jobs/{jobId} for the outcome
required:
- jobId
example:
jobId: 3f2b9c1e-5d47-4a8b-9f10-2c6de8a71b34
'400':
description: >-
Validation failure on the request, an ownerUserId does not belong to
the team, or the domain has too few free mailbox slots or is a
pre-warmed domain.
content:
application/problem+json:
schema:
oneOf:
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail
string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures
the pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message
on body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when
the request body
fails binding, FluentValidator rules, or when
route/query parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]`
array — clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the
form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling;
use `detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a
given resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced
error slug.
Emitted for most 4xx responses (business 400, 403,
404, 409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
examples:
validation_failed:
summary: Body validation failure
value:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /mailboxes
detail: >-
mailboxes must contain at most one mailbox with
isAdmin set to true.
owner_not_in_team:
summary: An ownerUserId is not a member of the team
value:
title: Bad Request
status: 400
detail: One or more ownerUserId values do not belong to this team.
code: procurementOrder.validation
not_enough_slots:
summary: The domain has too few free mailbox slots
value:
title: Bad Request
status: 400
detail: >-
This domain has 2 of 5 mailbox slots free, but 3 were
requested.
code: procurementOrder.validation
pre_warmed_domain:
summary: The domain is a pre-warmed domain
value:
title: Bad Request
status: 400
detail: >-
Domain 'outreach-hq.com' is a pre-warmed bundle; mailboxes
cannot be added to it.
code: procurementOrder.validation
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: The team is not registered for mailbox procurement
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
example:
title: Forbidden
status: 403
detail: >-
This team is not registered with the mailbox provider.
Register the team first.
code: procurementOrder.notRegistered
'404':
description: No domain with this ID belongs to the team
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Not Found
status: 404
detail: The requested resource was not found.
code: sequence.notFound
example:
title: Not Found
status: 404
detail: Domain with id '4182' not found or not accessible.
code: procurementOrder.domainNotFound
'409':
description: >-
A username or the admin mailbox already exists on the domain, the
domain is still provisioning or has expired, or the domain already
has a mailbox order in progress or in its cool-down of up to 15
minutes. An order for the same usernames placed within the last 24
hours returns its job reference in the detail.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Conflict
status: 409
detail: A resource with this name already exists.
code: sequence.duplicateName
examples:
username_taken:
summary: A username already exists on the domain
value:
title: Conflict
status: 409
detail: >-
The following usernames already exist on this domain:
john.doe.
code: procurementOrder.duplicateMailboxUsername
admin_exists:
summary: The domain already has an admin mailbox
value:
title: Conflict
status: 409
detail: Domain 'outreach-hq.com' already has an admin mailbox.
code: procurementOrder.adminMailboxAlreadyExists
domain_provisioning:
summary: The domain is still being provisioned
value:
title: Conflict
status: 409
detail: >-
Domain 'outreach-hq.com' is still being provisioned. Wait
for provisioning to finish and retry.
code: procurementOrder.domainNotReady
domain_expired:
summary: The domain subscription has expired
value:
title: Conflict
status: 409
detail: >-
Domain 'outreach-hq.com' has an expired subscription.
Renew the domain before adding mailboxes.
code: procurementOrder.domainNotReady
order_in_progress:
summary: The same mailboxes are already being added
value:
title: Conflict
status: 409
detail: The same mailboxes are already being added to this domain.
code: procurementOrder.duplicateRequest
order_already_placed:
summary: The same mailboxes were ordered within the last 24 hours
value:
title: Conflict
status: 409
detail: >-
This exact set of mailboxes was already ordered for this
domain within the last 24 hours. Job reference:
3f2b9c1e-5d47-4a8b-9f10-2c6de8a71b34.
code: procurementOrder.duplicateRequest
domain_cool_down:
summary: The domain is in a cool-down after a recent order
value:
title: Conflict
status: 409
detail: >-
This domain is in a short cool-down after a recent mailbox
order — up to 15 minutes. Retry after that.
code: procurementOrder.duplicateRequest
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: API calls quota exceeded! maximum admitted 100 per 1m.
'502':
description: >-
An earlier order for the same usernames could not be confirmed with
the provider. The detail carries that order's job reference.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
example:
title: Bad Gateway
status: 502
detail: >-
The payment was processed, but creation of the mailbox order
could not be confirmed with the provider. Support will
reconcile the order status — contact them with the request
time before ordering again. Job reference:
3f2b9c1e-5d47-4a8b-9f10-2c6de8a71b34.
code: procurementOrder.submitFailed
'503':
description: >-
The order could not be scheduled and no payment was charged, or an
earlier order for the same usernames could not be confirmed with the
provider. The second case carries that order's job reference.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Service Unavailable
status: 503
detail: Background-jobs service is temporarily unavailable.
code: backgroundJob.upstreamUnavailable
examples:
not_scheduled:
summary: The order could not be scheduled
value:
title: Service Unavailable
status: 503
detail: >-
The request could not be completed. No payment was
charged. Retry the request.
code: procurementOrder.temporarilyUnavailable
earlier_order_unconfirmed:
summary: >-
An earlier order for the same usernames could not be
confirmed
value:
title: Service Unavailable
status: 503
detail: >-
The mailbox order could not be confirmed with the
provider. It may or may not have been placed. Contact
support with the request time before retrying, so the
order status can be reconciled. Job reference:
3f2b9c1e-5d47-4a8b-9f10-2c6de8a71b34.
code: procurementOrder.temporarilyUnavailable
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.