> ## 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. # Nadaj zgodę na temat > Zapisuje istniejącego subskrybenta do tematu. Jeśli temat korzysta z double opt-in, zgoda jest tworzona jako `PENDING_CONFIRMATION` (`requiresConfirmation: true`), a subskrybent musi ją potwierdzić przez e-mail, zanim zostanie zapisany. Wymagany zakres: `consents:manage`. Dzierżawa: ograniczone do projektu klucza API. ## OpenAPI ````yaml /api-reference/openapi.pl.json post /api/v1/subscribers/{email}/consents 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)_`. 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/{email}/consents: parameters: - $ref: '#/components/parameters/EmailPath' post: tags: - Zgody summary: Nadaj zgodę na temat description: >- Zapisuje istniejącego subskrybenta do tematu. Jeśli temat korzysta z double opt-in, zgoda jest tworzona jako `PENDING_CONFIRMATION` (`requiresConfirmation: true`), a subskrybent musi ją potwierdzić przez e-mail, zanim zostanie zapisany. Wymagany zakres: `consents:manage`. Dzierżawa: ograniczone do projektu klucza API. operationId: grantConsent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GrantConsentRequest' examples: subscribeExisting: summary: Add an existing subscriber to a topic value: topicKey: APIT-1 source: preference-center ipAddress: 203.0.113.10 userAgent: Mozilla/5.0 sourceUrl: https://shop.example.com/prefs consentText: I agree to receive the newsletter formVersion: v3 responses: '201': description: >- Zgoda nadana (lub oczekująca potwierdzenia dla tematów z double opt-in) content: application/json: schema: $ref: '#/components/schemas/ConsentResponse' examples: pendingDoubleOptIn: summary: Topic requires confirmation value: topicKey: APIT-1 status: PENDING_CONFIRMATION requiresConfirmation: true grantedAt: '2026-06-24T10:20:00Z' confirmedAt: null tokenExpiresAt: '2026-06-26T10:20:00Z' subscribedDirectly: summary: Single opt-in topic value: topicKey: APIT-2 status: SUBSCRIBED requiresConfirmation: false grantedAt: '2026-06-24T10:20:00Z' confirmedAt: '2026-06-24T10:20:00Z' tokenExpiresAt: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: EmailPath: name: email in: path required: true description: URL-encoded subscriber email. schema: type: string format: email schemas: GrantConsentRequest: type: object properties: topicKey: type: string source: type: string ipAddress: type: string nullable: true userAgent: type: string nullable: true sourceUrl: type: string nullable: true consentText: type: string nullable: true formVersion: type: string nullable: true required: - topicKey - source ConsentResponse: type: object description: >- When requiresConfirmation is true, the topic uses double opt-in and the subscriber must confirm via email before they are subscribed. properties: topicKey: type: string status: type: string description: np. SUBSCRIBED, PENDING_CONFIRMATION, UNSUBSCRIBED. requiresConfirmation: type: boolean grantedAt: type: string format: date-time nullable: true confirmedAt: type: string format: date-time nullable: true tokenExpiresAt: type: string format: date-time 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: 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' NotFound: description: The resource does not exist in this project. 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_...`. ````