> ## 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 kampanię > Tworzy kampanię roboczą. Wymagany zakres: `campaigns:write`. Dzierżawa: ograniczone do projektu klucza API. ## OpenAPI ````yaml /api-reference/openapi.pl.json post /api/v1/campaigns 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/campaigns: post: tags: - Kampanie summary: Utwórz kampanię description: >- Tworzy kampanię roboczą. Wymagany zakres: `campaigns:write`. Dzierżawa: ograniczone do projektu klucza API. operationId: createCampaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' examples: draft: value: name: June Newsletter subject: Your June update previewText: What's new this month contentJson: '{"blocks":[]}' fromEmail: news@example.com fromName: Example topicIds: - 7b9c1f2e-2a1d-4d8a-9b1f-7e6c5d4b3a2f segmentIds: [] sendStrategy: DRAFT responses: '201': description: Kampania utworzona content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: schemas: CreateCampaignRequest: type: object properties: name: type: string maxLength: 200 subject: type: string maxLength: 500 previewText: type: string nullable: true contentJson: type: string nullable: true description: Treść sformatowana jako łańcuch JSON. contentText: type: string nullable: true fromEmail: type: string nullable: true fromName: type: string nullable: true topicIds: type: array items: type: string format: uuid nullable: true segmentIds: type: array items: type: string format: uuid nullable: true sendStrategy: type: string enum: - DRAFT - IMMEDIATE - SCHEDULED nullable: true scheduledAt: type: string format: date-time nullable: true required: - name - subject CampaignResponse: type: object properties: id: type: string format: uuid campaignKey: type: string nullable: true name: type: string subject: type: string nullable: true previewText: type: string nullable: true contentJson: type: string nullable: true contentText: type: string nullable: true status: type: string sendStrategy: type: string nullable: true topicIds: type: array items: type: string format: uuid nullable: true segmentIds: type: array items: type: string format: uuid nullable: true estimatedRecipientCount: type: integer format: int64 nullable: true scheduledAt: type: string format: date-time nullable: true completedAt: type: string format: date-time nullable: true fromEmail: type: string nullable: true fromName: type: string nullable: true preSendScore: type: integer nullable: true preSendStatus: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time 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' 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_...`. ````