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

# Create a subscriber

> Creates a subscriber in the key's project and subscribes them to the given topics in a single call. If a topic uses double opt-in, the resulting consent is `PENDING_CONFIRMATION`. Requires scope: `subscribers:write`. Tenancy: scoped to the API key's project.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/subscribers
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/subscribers:
    post:
      tags:
        - Subscribers
      summary: Create a subscriber
      description: >-
        Creates a subscriber in the key's project and subscribes them to the
        given topics in a single call. If a topic uses double opt-in, the
        resulting consent is `PENDING_CONFIRMATION`. Requires scope:
        `subscribers:write`. Tenancy: scoped to the API key's project.
      operationId: createSubscriber
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriberRequest'
            examples:
              addUserToTopics:
                summary: Add a customer's user to topics with consent
                value:
                  email: jane@example.com
                  firstName: Jane
                  lastName: Doe
                  topicKeys:
                    - APIT-1
                    - APIT-2
                  consent:
                    source: checkout-form
                    sourceUrl: https://shop.example.com/checkout
                    ipAddress: 203.0.113.10
                    userAgent: Mozilla/5.0
                    consentText: I agree to receive product updates
                    formVersion: v3
                  customFields:
                    plan: pro
      responses:
        '201':
          description: Subscriber created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberResponse'
              examples:
                created:
                  value:
                    subscriberKey: SUB-1A2B
                    email: jane@example.com
                    firstName: Jane
                    lastName: Doe
                    phone: null
                    status: ACTIVE
                    source: API
                    createdAt: '2026-06-24T10:15:00Z'
                    updatedAt: '2026-06-24T10:15:00Z'
        '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:
    CreateSubscriberRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        firstName:
          type: string
          maxLength: 50
          nullable: true
        lastName:
          type: string
          maxLength: 50
          nullable: true
        phone:
          type: string
          maxLength: 20
          nullable: true
        topicKeys:
          type: array
          items:
            type: string
          minItems: 1
        consent:
          $ref: '#/components/schemas/ConsentInfo'
        customFields:
          type: object
          additionalProperties:
            type: string
          nullable: true
      required:
        - email
        - topicKeys
        - consent
    SubscriberResponse:
      type: object
      properties:
        subscriberKey:
          type: string
          nullable: true
        email:
          type: string
          format: email
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        status:
          type: string
        source:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ConsentInfo:
      type: object
      properties:
        source:
          type: string
        sourceUrl:
          type: string
          nullable: true
        ipAddress:
          type: string
          nullable: true
        userAgent:
          type: string
          nullable: true
        consentText:
          type: string
          nullable: true
        formVersion:
          type: string
          nullable: true
      required:
        - source
    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_...`.

````