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

# Grant consent for a topic

> Subscribes an existing subscriber to a topic. If the topic uses double opt-in, the consent is created `PENDING_CONFIRMATION` (`requiresConfirmation: true`) and the subscriber must confirm via email before they are subscribed. Requires scope: `consents:manage`. Tenancy: scoped to the API key's project.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/subscribers/{email}/consents
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/{email}/consents:
    parameters:
      - $ref: '#/components/parameters/EmailPath'
    post:
      tags:
        - Consents
      summary: Grant consent for a topic
      description: >-
        Subscribes an existing subscriber to a topic. If the topic uses double
        opt-in, the consent is created `PENDING_CONFIRMATION`
        (`requiresConfirmation: true`) and the subscriber must confirm via email
        before they are subscribed. Requires scope: `consents:manage`. Tenancy:
        scoped to the API key's project.
      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: Consent granted (or pending confirmation for double opt-in topics)
          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: e.g. 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: 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'
    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_...`.

````