> ## Documentation Index
> Fetch the complete documentation index at: https://docs.railmail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a custom sending domain

> Sets up a custom sending domain for the project. Requires scope: `sending_domains:write`. Tenancy: the tenant is taken from the API key context, never the body.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/sending-domain
openapi: 3.1.0
info:
  title: Railmail Public API
  version: v1
  description: >-
    REST API for managing the Railmail email marketing platform
    programmatically.


    ## Authentication

    Every request must carry a project-scoped API key, either in the `X-API-Key`
    header or as `Authorization: Bearer rm_...`. Keys have the format
    `rm_(live|test)_<random>`. A key resolves to exactly one project; all reads
    and writes are automatically isolated to that project and its tenant. A key
    cannot read or modify another project's data.


    ## Scopes

    Every key carries a set of scopes. Each operation requires a specific scope,
    documented in that operation's description (for example `Requires scope:
    subscribers:write`). A request whose key lacks the required scope returns
    `403`.


    The full scope taxonomy: `subscribers:read|write`, `topics:read|write`,
    `segments:read|write`, `campaigns:read|write`, `automations:read|write`,
    `custom_fields:read|write`, `sending_domains:read|write`, `consents:manage`,
    `suppressions:manage`, `reports:read`, `billing:read`, `credits:read`.


    ## Rate limiting

    Requests are limited to 60 per minute per key. The response carries
    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. When
    exceeded, the API returns `429` with a `Retry-After` header.


    ## Errors

    All errors use RFC 7807 `application/problem+json` with `type`, `title`,
    `status`, `detail`, `instance`, `timestamp` and (for validation) `errors`.


    ## Canonical flow: add your users to your topics

    1. `GET /topics` to discover topic keys.

    2. `POST /subscribers` with `topicKeys` + `consent` to create a subscriber
    and subscribe in one call, OR `POST /subscribers/{email}/consents` to
    subscribe an existing subscriber.

    If a topic uses double opt-in, the consent is created `PENDING_CONFIRMATION`
    and the subscriber must confirm via the email they receive before they are
    subscribed.
  contact:
    name: Railmail
    url: https://railmail.app
servers:
  - url: https://api.railmail.app
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Subscribers
    description: Manage subscribers within the API key's project
  - name: Topics
    description: Manage subscription topics in the project
  - name: Consents
    description: Grant, read and revoke per-topic consent for a subscriber
  - name: Suppressions
    description: Manage the project suppression list
  - name: Campaigns
    description: Create, manage, schedule and send email campaigns
  - name: Segments
    description: Create, manage and populate subscriber segments
  - name: Custom Fields
    description: Define and manage subscriber custom field definitions
  - name: Automations
    description: Create, manage and control email automation workflows
  - name: Sending Domain
    description: Manage the project's custom sending domain and DNS verification
  - name: Campaign Reports
    description: Read campaign statistics, AI report, timeline and CSV export
  - name: Billing
    description: Read subscription, plans, invoices and usage for the account
  - name: AI Credits
    description: Read AI credit balance and transaction history for the account
  - name: Project
    description: Read the project the API key is scoped to
paths:
  /api/v1/sending-domain:
    post:
      tags:
        - Sending Domain
      summary: Set up a custom sending domain
      description: >-
        Sets up a custom sending domain for the project. Requires scope:
        `sending_domains:write`. Tenancy: the tenant is taken from the API key
        context, never the body.
      operationId: setupSendingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupSendingDomainRequest'
      responses:
        '201':
          description: Sending domain created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendingDomainResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    SetupSendingDomainRequest:
      type: object
      properties:
        domainName:
          type: string
      required:
        - domainName
    SendingDomainResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          nullable: true
        domainName:
          type: string
          nullable: true
        domainType:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        healthScore:
          type: integer
          nullable: true
        projectId:
          type: integer
          format: int64
          nullable: true
        dnsRecords:
          type: array
          items:
            $ref: '#/components/schemas/DnsRecordResponse'
        verifiedAt:
          type: string
          format: date-time
          nullable: true
        lastHealthCheckAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        suspensionReason:
          type: string
          nullable: true
        verificationAttempts:
          type: integer
        sendingAllowed:
          type: boolean
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    DnsRecordResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          nullable: true
        recordType:
          type: string
          nullable: true
        host:
          type: string
          nullable: true
        expectedValue:
          type: string
          nullable: true
        actualValue:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        lastCheckedAt:
          type: string
          format: date-time
          nullable: true
        failureReason:
          type: string
          nullable: true
    ProblemDetail:
      type: object
      description: RFC 7807 problem details.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri
        timestamp:
          type: string
          format: date-time
        errors:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation errors, present on 400/422.
      required:
        - type
        - title
        - status
  responses:
    BadRequest:
      description: Malformed request or invalid field values.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Forbidden:
      description: The API key lacks the required scope.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Conflict:
      description: The request conflicts with the current state of the resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    UnprocessableEntity:
      description: The request body failed domain validation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Epoch seconds when the window resets.
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    InternalError:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Project-scoped API key, format rm_(live|test)_... . May also be sent as
        `Authorization: Bearer rm_...`.

````