Sequenzy Receiving Domains API

openapi: 3.2.0
info:
  title: Sequenzy Receiving Domains API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Receiving Domains
  description: Domains and subdomains whose mail reaches your Inbox
paths:
  /receiving-domains:
    get:
      operationId: listReceivingDomains
      summary: List receiving domains
      description: Lists the domains and subdomains whose mail reaches your Inbox, in alphabetical order, with their status and the DNS records to publish. A workspace has one receiving domain; workspaces that set up several before keep them, and replies then use the sender's own domain or one on the same root, else the oldest verified one. Requires the websites:read scope. Marketer personal API keys cannot use receiving domain endpoints.
      tags:
      - Receiving Domains
      responses:
        '200':
          description: Receiving domains returned
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - receivingDomains
                properties:
                  success:
                    type: boolean
                    example: true
                  receivingDomains:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReceivingDomain'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the websites:read scope, or is a marketer personal key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    post:
      operationId: addReceivingDomain
      summary: Add receiving domain
      description: 'Adds your workspace''s receiving domain, a domain or subdomain whose mail should reach your Inbox, and returns the DNS records to publish. A workspace has one receiving domain. Once it is verified, replies to emails from all your sending domains come back to reply addresses on it, and its first verification turns Inbox on; until then replies use inbound.sequenzy.com. Mail for a domain goes wherever its MX records point, so a domain whose MX records already point at another mail service (Google Workspace, Microsoft 365, Cloudflare Email Routing) is refused: use a subdomain such as support.acme.com instead. When the workspace already has a receiving domain, a different name is refused with limit_reached before any DNS lookup. Adding a name this workspace already has returns it unchanged with created false, without checking its MX records again, so retries are safe. Adding the first receiving domain also sets the company''s reply domain mode to custom. Requires the websites:write scope and owner or admin access.'
      tags:
      - Receiving Domains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  minLength: 1
                  maxLength: 253
                  description: Domain or subdomain you own, such as acme.com or support.acme.com. Case and a trailing dot are ignored.
                  example: support.acme.com
            examples:
              subdomain:
                summary: Receive on a subdomain
                value:
                  domain: support.acme.com
      responses:
        '200':
          description: This workspace already has the domain; returned unchanged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivingDomainCreateResponse'
        '201':
          description: Receiving domain added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivingDomainCreateResponse'
              example:
                success: true
                created: true
                receivingDomain:
                  id: rd_abc123
                  domain: support.acme.com
                  status: pending
                  records:
                  - type: MX
                    name: support.acme.com
                    value: inbound-smtp.us-east-1.amazonaws.com
                    priority: 10
                    status: pending
                  - type: TXT
                    name: _amazonses.support.acme.com
                    value: pmBGN/7MjnfhTKUZ06Enqq1PeGUaOkw8lGhcfwefcHU=
                    status: pending
                  error: null
                  claimExpiresAt: '2026-10-17T09:00:00.000Z'
                  verifiedAt: null
                  lastCheckedAt: '2026-10-10T09:00:00.000Z'
                  createdAt: '2026-10-10T09:00:00.000Z'
        '400':
          description: Not a valid domain (code invalid_domain), or a Sequenzy domain or an email provider's domain such as gmail.com (code reserved_domain)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Enter a domain you own, such as acme.com or support.acme.com.
                code: invalid_domain
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: View-only access, the API key is missing the websites:write scope, or it is a marketer personal key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Another workspace receives on the name or sends from it or a parent domain (code domain_taken), the domain already receives email through another mail service such as Google Workspace or Microsoft 365 (code domain_has_mailbox), or this workspace already has a receiving domain (code limit_reached, checked before the MX lookup)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                domainTaken:
                  summary: Used by another workspace
                  value:
                    error: support.acme.com is already used by another workspace.
                    code: domain_taken
                domainHasMailbox:
                  summary: The domain already has a mailbox elsewhere
                  value:
                    error: acme.com already receives email through Google Workspace, so we can't receive it here without breaking that mailbox. Use a subdomain such as support.acme.com, or another domain you own.
                    code: domain_has_mailbox
                limitReached:
                  summary: The workspace already has a receiving domain
                  value:
                    error: A workspace has one receiving domain. Remove it first to use a different one.
                    code: limit_reached
        '422':
          description: Missing or empty domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestValidationError'
        '503':
          description: The domain's MX records could not be looked up right now (code dns_check_failed). Nothing was added; retry in a minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: We couldn't check where acme.com receives email right now. Try again in a minute.
                code: dns_check_failed
  /receiving-domains/{domain}:
    get:
      operationId: getReceivingDomain
      summary: Get receiving domain
      description: Returns one receiving domain from the latest stored check. To check its DNS now, use Verify receiving domain. Requires the websites:read scope.
      tags:
      - Receiving Domains
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        description: The receiving domain's name, such as support.acme.com, or its id.
        example: support.acme.com
      responses:
        '200':
          description: Receiving domain returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivingDomainResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the websites:read scope, or is a marketer personal key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not one of this workspace's receiving domains (code not_found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Receiving domain not found.
                code: not_found
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    delete:
      operationId: removeReceivingDomain
      summary: Remove receiving domain
      description: Removes a receiving domain and returns it as it was. Mail to every address on it stops arriving, including replies to emails already sent with reply addresses on it, and a branded inbox address on it is cleared. Remove Sequenzy's MX record from your DNS afterwards. Requires the websites:delete scope and owner or admin access.
      tags:
      - Receiving Domains
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        description: The receiving domain's name, such as support.acme.com, or its id.
        example: support.acme.com
      responses:
        '200':
          description: Receiving domain removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivingDomainResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: View-only access, the API key is missing the websites:delete scope, or it is a marketer personal key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not one of this workspace's receiving domains (code not_found), or company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /receiving-domains/{domain}/verify:
    post:
      operationId: verifyReceivingDomain
      summary: Verify receiving domain
      description: Checks the domain's DNS records and Amazon SES setup now instead of waiting for the next automatic check, and returns the result. The first time a receiving domain added with Add receiving domain becomes verified, Inbox turns on (replyTrackingEnabled becomes true). Domains moved from an older reply setup or added through Update inbox address leave the Inbox setting unchanged. Requires the websites:write scope and owner or admin access.
      tags:
      - Receiving Domains
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        description: The receiving domain's name, such as support.acme.com, or its id.
        example: support.acme.com
      responses:
        '200':
          description: Check finished; read status and error for the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivingDomainResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: View-only access, the API key is missing the websites:write scope, or it is a marketer personal key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not one of this workspace's receiving domains (code not_found), or company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    ReceivingDomain:
      type: object
      description: A domain or subdomain whose mail reaches your Inbox, such as acme.com or support.acme.com. Every address on it lands in Inbox. Once it is verified, replies to emails you send from any of your sending domains come back to reply addresses on it.
      required:
      - id
      - domain
      - status
      - records
      - error
      - claimExpiresAt
      - verifiedAt
      - lastCheckedAt
      - createdAt
      properties:
        id:
          type: string
          example: rd_abc123
        domain:
          type: string
          description: Lowercase domain name without a trailing dot.
          example: support.acme.com
        status:
          type: string
          enum:
          - pending
          - verified
          - failed
          description: 'verified: mail arrives and new reply addresses use the domain. pending: waiting for the DNS records; a newly added name stays reserved for your workspace for 7 days. failed: the domain was set up and something broke, or its 7-day reservation ran out before the records were found; mail that still arrives is accepted, and new reply addresses use inbound.sequenzy.com until it is fixed.'
        records:
          type: array
          description: DNS records to publish. Always the MX record; the TXT record at _amazonses.<domain> is listed only when Amazon SES needs proof that you own the name.
          items:
            $ref: '#/components/schemas/ReceivingDomainDnsRecord'
        error:
          type:
          - string
          - 'null'
          description: What to fix, when known. Always null while verified.
          example: Add the TXT record so Amazon SES can confirm you own support.acme.com.
        claimExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When a new domain that has never verified stops being reserved for your workspace, after which another workspace may add it. Null once verified, and for domains moved over from an earlier reply setup.
        verifiedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the domain first verified.
        lastCheckedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    ReceivingDomainCreateResponse:
      type: object
      required:
      - success
      - created
      - receivingDomain
      properties:
        success:
          type: boolean
          example: true
        created:
          type: boolean
          description: True when the domain was added; false when this workspace already had it.
        receivingDomain:
          $ref: '#/components/schemas/ReceivingDomain'
    RequestValidationError:
      type: object
      description: Returned with status 422 when the request does not match the endpoint's field types, for example a missing required field, a value outside an allowed set, or a number sent as a string. Fix the field named in `property` and retry.
      properties:
        type:
          type: string
          example: validation
        'on':
          type: string
          description: Request part that failed, such as `body` or `query`. A query parameter outside its numeric range reports `property` here, with `property` set to `root` and the parameter value in `found`.
          example: body
        property:
          type: string
          description: JSON Pointer to the first failing field.
          example: /enrollmentMode
        message:
          type: string
          example: Expected union value
        summary:
          type: string
          description: Readable description of the first failure.
          example: 'Property ''enrollmentMode'' must be one of: unlimited, one_time, matching_field'
        found:
          description: The request part as received, after unknown fields were removed.
        errors:
          type: array
          maxItems: 10
          description: The first failures found, at most 10.
          items:
            type: object
            properties:
              path:
                type: string
                example: /enrollmentMode
              message:
                type: string
              summary:
                type: string
              allowedValues:
                type: array
                description: Accepted values when the field takes a fixed set of values.
                items: {}
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    ReceivingDomainDnsRecord:
      type: object
      required:
      - type
      - name
      - value
      - status
      properties:
        type:
          type: string
          enum:
          - MX
          - TXT
        name:
          type: string
          description: Fully qualified record name.
          example: support.acme.com
        value:
          type: string
          example: inbound-smtp.us-east-1.amazonaws.com
        priority:
          type: integer
          description: MX records only.
          example: 10
        status:
          type: string
          enum:
          - pending
          - verified
          - misconfigured
          description: misconfigured (MX only) means the name also has MX records for another mail service, which would split its mail.
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
    ReceivingDomainResponse:
      type: object
      required:
      - success
      - receivingDomain
      properties:
        success:
          type: boolean
          example: true
        receivingDomain:
          $ref: '#/components/schemas/ReceivingDomain'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token