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

# Utwórz subskrybenta

> Tworzy subskrybenta w projekcie klucza i zapisuje go do podanych tematów w jednym wywołaniu. Jeśli temat korzysta z double opt-in, wynikowa zgoda ma status `PENDING_CONFIRMATION`. Wymagany zakres: `subscribers:write`. Dzierżawa: ograniczone do projektu klucza API.



## OpenAPI

````yaml /api-reference/openapi.pl.json post /api/v1/subscribers
openapi: 3.1.0
info:
  title: Railmail Public API
  version: v1
  description: >-
    REST API do programistycznego zarządzania platformą email marketingu
    Railmail.


    ## Uwierzytelnianie

    Każde żądanie musi zawierać klucz API przypisany do projektu — w nagłówku
    `X-API-Key` lub jako `Authorization: Bearer rm_...`. Klucze mają format
    `rm_(live|test)_<losowy>`. Klucz odpowiada dokładnie jednemu projektowi;
    wszystkie odczyty i zapisy są automatycznie izolowane do tego projektu i
    jego tenanta. Klucz nie może odczytać ani zmodyfikować danych innego
    projektu.


    ## Zakresy

    Każdy klucz posiada zestaw zakresów. Każda operacja wymaga określonego
    zakresu, opisanego w jej opisie (na przykład `Wymagany zakres:
    subscribers:write`). Żądanie, którego klucz nie ma wymaganego zakresu,
    zwraca `403`.


    Pełna taksonomia zakresów: `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`.


    ## Limity zapytań

    Żądania są ograniczone do 60 na minutę na klucz. Odpowiedź zawiera nagłówki
    `X-RateLimit-Limit`, `X-RateLimit-Remaining` i `X-RateLimit-Reset`. Po
    przekroczeniu limitu API zwraca `429` z nagłówkiem `Retry-After`.


    ## Błędy

    Wszystkie błędy używają RFC 7807 `application/problem+json` z polami `type`,
    `title`, `status`, `detail`, `instance`, `timestamp` oraz (przy walidacji)
    `errors`.


    ## Typowy przepływ: dodaj użytkowników do swoich tematów

    1. `GET /topics`, aby odkryć klucze tematów.

    2. `POST /subscribers` z `topicKeys` + `consent`, aby utworzyć subskrybenta
    i zapisać go w jednym wywołaniu, LUB `POST /subscribers/{email}/consents`,
    aby zapisać istniejącego subskrybenta.

    Jeśli temat korzysta z double opt-in, zgoda jest tworzona jako
    `PENDING_CONFIRMATION`, a subskrybent musi ją potwierdzić przez otrzymaną
    wiadomość, zanim zostanie zapisany.
  contact:
    name: Railmail
    url: https://railmail.app
servers:
  - url: https://api.railmail.app
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Subskrybenci
    description: Zarządzaj subskrybentami w projekcie klucza API
  - name: Tematy
    description: Zarządzaj tematami subskrypcji w projekcie
  - name: Zgody
    description: Nadawaj, odczytuj i cofaj zgodę subskrybenta per temat
  - name: Wykluczenia
    description: Zarządzaj listą wykluczeń projektu
  - name: Kampanie
    description: Twórz, zarządzaj, planuj i wysyłaj kampanie e-mail
  - name: Segmenty
    description: Twórz, zarządzaj i wypełniaj segmenty subskrybentów
  - name: Pola niestandardowe
    description: Definiuj i zarządzaj polami niestandardowymi subskrybentów
  - name: Automatyzacje
    description: Twórz, zarządzaj i kontroluj przepływy automatyzacji e-mail
  - name: Domena wysyłkowa
    description: Zarządzaj własną domeną wysyłkową projektu i weryfikacją DNS
  - name: Raporty kampanii
    description: Odczytuj statystyki kampanii, raport AI, oś czasu i eksport CSV
  - name: Rozliczenia
    description: Odczytuj subskrypcję, plany, faktury i zużycie dla konta
  - name: Kredyty AI
    description: Odczytuj saldo kredytów AI i historię transakcji dla konta
  - name: Projekt
    description: Odczytaj projekt, do którego przypisany jest klucz API
paths:
  /api/v1/subscribers:
    post:
      tags:
        - Subskrybenci
      summary: Utwórz subskrybenta
      description: >-
        Tworzy subskrybenta w projekcie klucza i zapisuje go do podanych tematów
        w jednym wywołaniu. Jeśli temat korzysta z double opt-in, wynikowa zgoda
        ma status `PENDING_CONFIRMATION`. Wymagany zakres: `subscribers:write`.
        Dzierżawa: ograniczone do projektu klucza API.
      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: Subskrybent utworzony
          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: Błędy walidacji per pole, obecne przy 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_...`.

````