> ## 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.

# Buy a pre-warmed domain

> <Tip>
  **New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
</Tip>

<small>_Requires the `channels:write` scope (or a broader one that includes it)._</small>

Buys one pre-warmed bundle: the domain and every mailbox already warming on it. A bundle is sold whole — you cannot pick a subset of its mailboxes, and you cannot add more in the same order.

Send serviceProvider and domain.domainName exactly as the available pre-warmed domains list returns them. Price the order first with the estimate: this endpoint charges the card on file.

Returns a jobId and a Location header — poll GET /v3/background-jobs/{jobId} for the outcome. On success its jsonDataResult carries the registered `domain` and the `mailboxes` that came with it, each with its e-mail, username and name.

Two purchases of the same domain by the same team inside 24 hours are refused rather than charged twice, and the detail carries the job reference of the first one: 409 when the first purchase is still running or was placed, and the first job's own 502 or 503 when it failed after the payment step.

When the job ends as Failed, its jsonDataResult carries an `errorCode` and a message — on `domain.failureMessage` for `preWarmedDomain.domainNotFound`, otherwise on the top-level `failureMessage`. No payment was charged, except for `preWarmedDomain.submitFailed` and for a `preWarmedDomain.temporarilyUnavailable` whose message says the payment or the order could not be confirmed.

| `errorCode` | Meaning |
|---|---|
| `preWarmedDomain.domainNotFound` | The bundle is no longer on sale — someone else bought it, or the provider withdrew it. Pick another from the available list. |
| `preWarmedDomain.validation` | The bundle or the current plan cannot take the order. |
| `preWarmedDomain.paymentDeclined` | The payment provider declined the payment. |
| `preWarmedDomain.paymentActionRequired` | The saved payment method needs interactive authentication. Complete it in the app, then retry. |
| `preWarmedDomain.upstreamBadRequest` | The provider rejected the order. Check the domain name and service provider. |
| `preWarmedDomain.upstreamUnavailable` | The provider was unreachable. Retry later. |
| `preWarmedDomain.temporarilyUnavailable` | A transient failure. When the message says no payment was charged, retry. When it says the payment or the order may or may not have gone through, do not retry — contact support with the jobId. |
| `preWarmedDomain.featureDisabled` | Pre-warmed domains were switched off for the team, or dropped from its plan, while the job ran. |
| `preWarmedDomain.unknown` | The order could not be reliably priced, or the inventory could not be checked. Retry, or contact support. |
| `preWarmedDomain.submitFailed` | Payment was taken, but the order reference could not be resolved. Contact support with the jobId before ordering again. |

If the job ends as Expired, nothing reported progress for 26 hours and the job was closed: jsonDataResult is `{"timedOut": true}`, with no `errorCode`. The outcome is unknown — the payment may have been taken and the order placed. Do not order again: check GET /v3/email-accounts/procurement/pre-warmed-domains, where the domain appears once the provider accepted the order, and contact support with the jobId if it is not there.



## OpenAPI

````yaml /api-reference/bundled.yaml post /v3/email-accounts/procurement/pre-warmed-domains/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: Contact List Folders
    description: Group contact lists into personal and shared folders
  - 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, sequence structure, and playbook/knowledge-base connections
  - name: AI SDR Sequence Structures
    description: >-
      Browse the sequence structures — reusable outlines of AI SDR sequence
      steps — that can be applied to AI SDR sequences
  - 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, and renew them
  - name: Pre-warmed Domains
    description: >-
      Find pre-warmed domains on sale, with mailboxes that are already warming,
      and list the ones your team bought
  - name: Mailboxes
    description: >-
      Add mailboxes to domains your team already bought, priced before you
      order, and reconnect them
  - name: User Account
    description: Account information and authentication verification
  - name: API Keys
    description: Create, list, edit and delete API keys, as the Settings page does
  - name: Teams
    description: Add existing users of your organization to its teams
  - 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, your current usage and the packages that raise them
  - name: Support Requests
    description: Raise and follow support requests with Reply's support team
  - 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/pre-warmed-domains/purchase:
    post:
      tags:
        - Pre-warmed Domains
      summary: Buy a pre-warmed domain
      description: >-
        <Tip>
          **New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
        </Tip>


        <small>_Requires the `channels:write` scope (or a broader one that
        includes it)._</small>


        Buys one pre-warmed bundle: the domain and every mailbox already warming
        on it. A bundle is sold whole — you cannot pick a subset of its
        mailboxes, and you cannot add more in the same order.


        Send serviceProvider and domain.domainName exactly as the available
        pre-warmed domains list returns them. Price the order first with the
        estimate: this endpoint charges the card on file.


        Returns a jobId and a Location header — poll GET
        /v3/background-jobs/{jobId} for the outcome. On success its
        jsonDataResult carries the registered `domain` and the `mailboxes` that
        came with it, each with its e-mail, username and name.


        Two purchases of the same domain by the same team inside 24 hours are
        refused rather than charged twice, and the detail carries the job
        reference of the first one: 409 when the first purchase is still running
        or was placed, and the first job's own 502 or 503 when it failed after
        the payment step.


        When the job ends as Failed, its jsonDataResult carries an `errorCode`
        and a message — on `domain.failureMessage` for
        `preWarmedDomain.domainNotFound`, otherwise on the top-level
        `failureMessage`. No payment was charged, except for
        `preWarmedDomain.submitFailed` and for a
        `preWarmedDomain.temporarilyUnavailable` whose message says the payment
        or the order could not be confirmed.


        | `errorCode` | Meaning |

        |---|---|

        | `preWarmedDomain.domainNotFound` | The bundle is no longer on sale —
        someone else bought it, or the provider withdrew it. Pick another from
        the available list. |

        | `preWarmedDomain.validation` | The bundle or the current plan cannot
        take the order. |

        | `preWarmedDomain.paymentDeclined` | The payment provider declined the
        payment. |

        | `preWarmedDomain.paymentActionRequired` | The saved payment method
        needs interactive authentication. Complete it in the app, then retry. |

        | `preWarmedDomain.upstreamBadRequest` | The provider rejected the
        order. Check the domain name and service provider. |

        | `preWarmedDomain.upstreamUnavailable` | The provider was unreachable.
        Retry later. |

        | `preWarmedDomain.temporarilyUnavailable` | A transient failure. When
        the message says no payment was charged, retry. When it says the payment
        or the order may or may not have gone through, do not retry — contact
        support with the jobId. |

        | `preWarmedDomain.featureDisabled` | Pre-warmed domains were switched
        off for the team, or dropped from its plan, while the job ran. |

        | `preWarmedDomain.unknown` | The order could not be reliably priced, or
        the inventory could not be checked. Retry, or contact support. |

        | `preWarmedDomain.submitFailed` | Payment was taken, but the order
        reference could not be resolved. Contact support with the jobId before
        ordering again. |


        If the job ends as Expired, nothing reported progress for 26 hours and
        the job was closed: jsonDataResult is `{"timedOut": true}`, with no
        `errorCode`. The outcome is unknown — the payment may have been taken
        and the order placed. Do not order again: check GET
        /v3/email-accounts/procurement/pre-warmed-domains, where the domain
        appears once the provider accepted the order, and contact support with
        the jobId if it is not there.
      operationId: PurchasePreWarmedDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: PurchasePreWarmedDomainRequest
              description: >-
                Same shape and rules for the estimate and the purchase, so one
                body can be posted to both.
              properties:
                serviceProvider:
                  type: string
                  enum:
                    - Google
                    - Microsoft
                  description: >-
                    Mailbox provider the bundle is listed with,
                    case-insensitive. Must be the provider the domain was found
                    under — a bundle is not visible to the other one.
                domain:
                  type: object
                  properties:
                    domainName:
                      type: string
                      maxLength: 253
                      description: >-
                        The pre-warmed domain to buy, exactly as the available
                        pre-warmed domains list returns it, including the TLD.
                    forwardTo:
                      type: string
                      maxLength: 2048
                      description: >-
                        Optional http(s) URL that visitors of the domain are
                        redirected to. A URL, never an email address; omit it to
                        leave the domain without a redirect.
                  required:
                    - domainName
              required:
                - serviceProvider
                - domain
              example:
                serviceProvider: Google
                domain:
                  domainName: trademomentum.co
                  forwardTo: https://example.com
      responses:
        '202':
          description: Order accepted; poll the returned job for the outcome
          headers:
            Location:
              description: Relative path of the background job to poll
              schema:
                type: string
                example: v3/background-jobs/4f1d0f6e-9a1c-4f2e-bd2a-1f2f3a4b5c6d
          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 body.
          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:
                          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.
              examples:
                validation_failed:
                  summary: Body validation failure
                  value:
                    title: Validation failed
                    status: 400
                    detail: The request body contains validation errors.
                    errors:
                      - pointer: /domain/forwardTo
                        detail: >-
                          forwardTo must be a valid HTTP or HTTPS URL, not an
                          email address.
                service_provider_missing:
                  summary: serviceProvider is missing
                  value:
                    title: Validation failed
                    status: 400
                    detail: The request body contains validation errors.
                    errors:
                      - pointer: /serviceProvider
                        detail: serviceProvider is required.
        '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: >-
            Pre-warmed domains are off for the team or not included in its plan,
            or 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>.<variant>"`.


                              * `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
              examples:
                feature_disabled:
                  summary: Pre-warmed domains are not enabled for the team
                  value:
                    title: Forbidden
                    status: 403
                    detail: Pre-warmed domains are not enabled for your team.
                    code: preWarmedDomain.featureDisabled
                not_in_plan:
                  summary: Pre-warmed domains are not included in the team's plan
                  value:
                    title: Forbidden
                    status: 403
                    detail: Pre-warmed domains are not included in your team's plan.
                    code: preWarmedDomain.featureDisabled
                not_registered:
                  summary: The team is not registered for mailbox procurement
                  value:
                    title: Forbidden
                    status: 403
                    detail: >-
                      This team is not registered with the mailbox provider.
                      Register the team first.
                    code: preWarmedDomain.notRegistered
        '409':
          description: >-
            The same domain is already being bought, or was bought by this team
            within the last 24 hours
          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>.<variant>"`.


                              * `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:
                in_progress:
                  summary: A purchase of this domain is still running
                  value:
                    title: Conflict
                    status: 409
                    detail: >-
                      A purchase of this pre-warmed domain is already being
                      processed.
                    code: preWarmedDomain.duplicateRequest
                placed_recently:
                  summary: Already placed within the last 24 hours
                  value:
                    title: Conflict
                    status: 409
                    detail: >-
                      A purchase of this pre-warmed domain was already placed
                      within the last 24 hours. Job reference:
                      4f1d0f6e-9a1c-4f2e-bd2a-1f2f3a4b5c6d.
                    code: preWarmedDomain.duplicateRequest
        '422':
          description: The workspace has no card on file to charge
          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.
                  - type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Stable, machine-readable error slug in the form

                          `"<resource>.<variant>"`.


                          * `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: Unprocessable Entity
                status: 422
                detail: >-
                  No active payment method is available for this workspace. Add
                  a payment card in billing settings and retry the request.
                code: preWarmedDomain.noPaymentMethod
        '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: >-
            A purchase of this domain within the last 24 hours was paid for, but
            its order reference could not be resolved. Contact support with the
            job reference before ordering again.
          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>.<variant>"`.


                              * `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 mailbox order was submitted, but the background job's
                  order reference could not be resolved. Contact support with
                  the request time so the order status can be reconciled. Job
                  reference: 4f1d0f6e-9a1c-4f2e-bd2a-1f2f3a4b5c6d.
                code: preWarmedDomain.submitFailed
        '503':
          description: >-
            The request could not be scheduled and no payment was charged —
            retry. With a job reference in the detail, it is the answer of an
            earlier purchase of this domain within the last 24 hours whose
            payment or order could not be confirmed: do not retry, contact
            support with the 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>.<variant>"`.


                              * `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: preWarmedDomain.temporarilyUnavailable
                earlier_outcome_unknown:
                  summary: An earlier purchase of this domain is unconfirmed
                  value:
                    title: Service Unavailable
                    status: 503
                    detail: >-
                      The payment could not be confirmed. It may or may not have
                      been taken. Contact support with the request time before
                      retrying, so the payment status can be reconciled. Job
                      reference: 4f1d0f6e-9a1c-4f2e-bd2a-1f2f3a4b5c6d.
                    code: preWarmedDomain.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 <your-api-key>

        ```


        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.