> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Recipient

> Add one recipient to a triggered campaign, the way an `api` trigger works: call this when something happens in your CRM or form. The email sends after the trigger's `delay_minutes`. Suppressed, unsubscribed and bounced addresses are never sent to.

The campaign must be started and not paused. A paused or never started campaign refuses new recipients with `409` rather than queueing them. A person enters once: a second entry for the same person returns `200` `already_entered`. Send an `occurrence_id` so a retry of the same event is a no-op (`200` `already_entered`). A `422` names why the address cannot be sent to in `details.reason`. A malformed body (a missing or badly formatted `email`, an unknown key) is a 400. A well-formed address that cannot be sent to is a 422; `details.reason` says why, for example `suppressed` for an address that has unsubscribed or is suppressed for this organization or sender.



## OpenAPI

````yaml /api-reference/openapi.json post /email/campaigns/{id}/recipients
openapi: 3.1.0
info:
  title: Political Comms API
  summary: >-
    Direct-to-carrier political texting API for campaigns, PACs, advocacy
    organizations, fundraisers, and elected officials.
  description: >-
    Public REST API for the Political Comms platform. Surfaces include Projects
    (compose, test, schedule, send, and triggered projects that text each person
    a trigger brings in), Conversations (read inbound threads and reply inside
    them), Lists (one import for phone numbers and emails, and analysis), Media
    Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains,
    Webhook Endpoints, Phone Numbers, Analytics, and Billing.


    Authentication is an API key passed in the `X-API-Key` header. Keys are
    generated from the dashboard at Admin → API and are prefixed `pc_live_`. All
    POST and PATCH endpoints that mutate state are designed to be safe to retry,
    with optional `Idempotency-Key` headers for stronger guarantees. Rate limit
    is 600 requests per minute per key (bursts up to 600, refilling at 10 per
    second, the same for every scope; the `X-RateLimit-Limit` header reports
    your key's exact limit, and `Retry-After` on a 429 is the seconds until your
    next request is allowed).


    Webhooks emit `message.sent`, `message.delivered`, `message.failed`,
    `message.replied`, and `link.clicked` events, plus email events including
    `email.sent`, `email.failed` and `email.opened`. Payloads are HMAC-signed;
    validate the signature before trusting any payload.


    A Model Context Protocol (MCP) server is available at
    https://docs.politicalcomms.com/mcp for AI agents that need to search the
    documentation programmatically. The developer hub at
    https://politicalcomms.com/developers/ has quickstart examples in cURL, raw
    HTTP, and Python.


    Triggered projects and email campaigns have no contact list: each person is
    added when a trigger fires (a WinRed or Anedot donation, a link click or
    reply in another project or campaign, or an API call or inbound hook URL),
    and gets one message, immediately or after a delay.
  version: 1.14.0
  termsOfService: https://politicalcomms.com/terms/
  contact:
    name: Political Comms Support
    email: support@politicalcomms.com
    url: https://docs.politicalcomms.com
  license:
    name: Proprietary
    url: https://politicalcomms.com/terms/
  x-logo:
    url: https://politicalcomms.com/images/brand/pcomms-logo-left-of-text.png
    altText: Political Comms
    backgroundColor: '#ffffff'
    href: https://politicalcomms.com/
  x-mcp:
    url: https://docs.politicalcomms.com/mcp
    discovery_url: https://docs.politicalcomms.com/.well-known/mcp
    transport: http
    auth: none
    tools:
      - search_political_comms
      - query_docs_filesystem_political_comms
      - submit_feedback
servers:
  - url: https://api.politicalcomms.com/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Projects
    description: Create, edit, test, schedule, and inspect projects.
  - name: Conversations
    description: >-
      Read inbound threads and reply inside them from the same number.
      Conversations are created by project sends; the API never starts one.
  - name: Phone Numbers
    description: List phone numbers across 10DLC campaigns and toll-free verifications.
  - name: Toll-Free Verifications
    description: >-
      List toll-free verifications (carrier registrations) across your
      organization hierarchy.
  - name: Brands
    description: List brands across your organization hierarchy.
  - name: 10DLC Campaigns
    description: >-
      List 10DLC campaigns (carrier registrations) across your organization
      hierarchy.
  - name: Email Campaigns
    description: >-
      Create, schedule, and report on email campaigns. Pause, resume, and test
      sends are deliverability decisions a human makes while watching a send,
      and live in the dashboard.
  - name: Email Templates
    description: Create and read saved email templates.
  - name: Email Senders
    description: >-
      Read the sender identities (From addresses) on your verified domains.
      Identities carry the physical mailing address and paid-for-by disclaimer,
      so they are created and edited in the dashboard.
  - name: Email Suppressions
    description: >-
      Addresses that will not be emailed: unsubscribes, bounces, complaints, and
      addresses you add. Read, add, and lift them in bulk to keep your own
      opt-out record in sync with ours. They apply automatically to every email
      send.
  - name: Contact Lists
    description: >-
      List, import, and analyze lists. One import brings in phone numbers,
      emails, or both, or a do-not-contact file.
  - name: Tags
    description: >-
      Label contacts and send to the label. Manual tags have members you add and
      remove; activity tags (donated, clicked, responded, sent) apply by
      themselves. Send to tags with `tag_ids` on projects and email campaigns.
  - name: Media Files
    description: List, import, and fetch media files.
  - name: Sending Domains
    description: >-
      Read the sending domains in your organization and the DNS records to
      publish. Domains are added in the dashboard: DNS is published by hand, so
      creation is not part of the API.
  - name: Tracking Domains
    description: >-
      List active link-tracking domains. Use the returned ids as
      `link_tracking_domain_id` on project create/update.
  - name: Webhook Endpoints
    description: >-
      Read your webhook endpoints and whether deliveries to them are failing.
      Endpoints are created, edited and re-enabled in the dashboard, where the
      signing secret is shown.
  - name: Organizations
    description: List descendant organizations and hierarchy.
  - name: Billing
    description: Usage and billing data across your organization.
  - name: Analytics
    description: Message statistics and delivery performance.
paths:
  /email/campaigns/{id}/recipients:
    post:
      tags:
        - Email Campaigns
      summary: Add Recipient
      description: >-
        Add one recipient to a triggered campaign, the way an `api` trigger
        works: call this when something happens in your CRM or form. The email
        sends after the trigger's `delay_minutes`. Suppressed, unsubscribed and
        bounced addresses are never sent to.


        The campaign must be started and not paused. A paused or never started
        campaign refuses new recipients with `409` rather than queueing them. A
        person enters once: a second entry for the same person returns `200`
        `already_entered`. Send an `occurrence_id` so a retry of the same event
        is a no-op (`200` `already_entered`). A `422` names why the address
        cannot be sent to in `details.reason`. A malformed body (a missing or
        badly formatted `email`, an unknown key) is a 400. A well-formed address
        that cannot be sent to is a 422; `details.reason` says why, for example
        `suppressed` for an address that has unsubscribed or is suppressed for
        this organization or sender.
      operationId: addEmailCampaignRecipient
      parameters:
        - $ref: '#/components/parameters/IdPath'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  description: The recipient's email address.
                fields:
                  type: object
                  maxProperties: 50
                  additionalProperties:
                    type:
                      - string
                      - number
                      - boolean
                    maxLength: 1024
                  description: >-
                    Optional values for this recipient, up to 50 keys with
                    scalar values. Each is stored as a string of up to 1024
                    characters, can be used as a merge tag in the message (for
                    example `{first_name}`), and appears in reports, exports and
                    the `contact.custom_fields` of outbound webhooks.
                occurrence_id:
                  type: string
                  maxLength: 128
                  description: >-
                    Your own id for the event that adds this person. Sending the
                    same `occurrence_id` again is a no-op, so a retry cannot add
                    or send twice.
              additionalProperties: false
            example:
              email: ada@example.org
              fields:
                first_name: Ada
                amount: 25
              occurrence_id: evt_123
      responses:
        '200':
          description: >-
            Nothing was added because this person or this `occurrence_id` was
            already entered; `reason` says which. A safe answer to a retry.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/TriggerRecipientResult'
                additionalProperties: true
              example:
                success: true
                data:
                  status: already_entered
                  reason: duplicate
        '202':
          description: Recipient queued. `send_at` is when the message will send.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/TriggerRecipientResult'
                additionalProperties: true
              example:
                success: true
                data:
                  status: queued
                  send_at: '2026-11-13T14:00:00.000Z'
        '400':
          description: >-
            The body failed validation (`VALIDATION_ERROR`, including an
            `email_column` that is not a header, with `details: { field:
            "email_column", headers }`, or a named column whose first rows are
            not what it was chosen for, such as `The column "SURVEY_LINK" does
            not contain email addresses. Choose the column that holds emails, or
            set the email column to None.` with `details: { field }`), the phone
            column is not a header (`PHONE_COLUMN_NOT_FOUND`, `details: {
            phoneColumn, headers }`), a merge tag is invalid
            (`INVALID_MERGE_TAGS`, `UNKNOWN_STANDARD_TAG`,
            `MERGE_TAG_COLUMN_NOT_FOUND`, `INVALID_MERGE_TAG_NAME`), the file is
            not a readable CSV (`INVALID_CSV`), the brand belongs to another
            organization than `organization_id` (`BRAND_ORG_MISMATCH`), or
            `source_url` is not a public HTTPS URL (`INVALID_SOURCE_URL`).
            Nothing is written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: phone_column "Phone" not found in CSV headers
                code: PHONE_COLUMN_NOT_FOUND
                correlationId: 030bf857-922f-4b82-8fca-c5b0769c1590
                details:
                  phoneColumn: Phone
                  headers:
                    - first_name
                    - cell
                    - email
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The API key lacks the required permission scope, the requested
            resource belongs to an organization outside the key's hierarchy, or
            the organization is not entitled to this feature.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AuthErrorResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingScope:
                  summary: Key lacks the required permission scope
                  value:
                    error: Insufficient permissions
                    message: >-
                      This API key does not have the required permissions:
                      public:write
                orgAccessDenied:
                  summary: Resource outside the key's organization hierarchy
                  value:
                    error: >-
                      Access denied: You do not have permission to access this
                      organization's data
                    code: ORG_ACCESS_DENIED
                    correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
                entitlementRequired:
                  summary: Organization is not entitled to this feature
                  value:
                    error: This feature requires enablement by Political Comms
                    code: ENTITLEMENT_REQUIRED
                    details:
                      entitlement: email
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Not accepting recipients. Error code CONFLICT when the campaign is
            not triggered or is not active (a paused or never started one
            refuses recipients rather than queueing them), or CONTACT_OPTED_OUT
            when this address is opted out or suppressed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            The address cannot be sent to. Error code VALIDATION_ERROR;
            `details` carries `field` and `reason`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: email cannot be sent to
                code: VALIDATION_ERROR
                details:
                  field: email
                  reason: invalid
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: Resource ID
      schema:
        type: string
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 16
        maxLength: 200
      description: >-
        Optional idempotency key: a unique string of 16-200 printable ASCII
        characters (a UUID is recommended). Retrying the write with the same key
        within 24 hours returns the stored response of the first call with an
        `X-Idempotent-Replayed: true` response header instead of executing it
        again. Reusing a key with a different request body returns `422`
        (`IDEMPOTENCY_MISMATCH`); a duplicate sent while the first call is still
        running returns `409` with a `Retry-After` header. Keys are scoped per
        endpoint and organization.
  schemas:
    TriggerRecipientResult:
      type: object
      description: The outcome of adding one recipient.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - queued
            - already_entered
        send_at:
          type: string
          format: date-time
          description: >-
            Present when `status` is `queued`: when the message will send, after
            any delay and any overnight hold.
        reason:
          type: string
          enum:
            - duplicate
            - already_entered
          description: >-
            Present when `status` is `already_entered`. `duplicate`: this
            `occurrence_id` was already received. `already_entered`: this person
            already entered; a person is sent a triggered project or campaign
            once.
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. VALIDATION_ERROR,
            ORG_ACCESS_DENIED, PROJECT_NOT_FOUND.
        correlationId:
          type: string
          description: Request correlation ID; include it in support requests.
        details:
          type:
            - array
            - object
          description: >-
            Present on some errors. For VALIDATION_ERROR, an array of { field,
            message, code } with one entry per rejected field (field is the
            dotted path); an object for other codes (e.g. insufficient-balance
            shortfall).
      required:
        - error
        - code
      additionalProperties: true
      description: >-
        Standard error body produced by the API error handler for 4xx/5xx
        responses.
    AuthErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Short error summary.
        message:
          type: string
          description: Human-readable detail.
      required:
        - error
        - message
      additionalProperties: true
      description: >-
        Error body returned by the API-key authentication layer (401 and
        permission 403s).
    RateLimitErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        message:
          type: string
        code:
          type: string
          enum:
            - RATE_LIMIT_EXCEEDED
        statusCode:
          type: integer
          enum:
            - 429
        retryAfter:
          type: integer
          description: >-
            Seconds until the rate-limit window resets. Also sent as the
            Retry-After header.
      required:
        - success
        - error
        - code
        - statusCode
        - retryAfter
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, malformed, revoked, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorResponse'
          example:
            error: API key required
            message: Please provide an API key in the X-API-Key header
    NotFound:
      description: Resource not found or not visible to this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Project not found
            code: PROJECT_NOT_FOUND
            correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
    RateLimited:
      description: Rate limit exceeded. Check the Retry-After header.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
          example:
            success: false
            error: Rate limit exceeded
            message: Maximum 600 requests per 60 seconds
            code: RATE_LIMIT_EXCEEDED
            statusCode: 429
            retryAfter: 3
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: An unexpected error occurred. Please try again later.
            code: INTERNAL_ERROR
            correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Authenticate every request by passing your API key in the X-API-Key
        header. Keys are scoped to your organization hierarchy. A key carries up
        to three permissions: `public:read` for GET requests, `public:write` for
        POST, PATCH, and PUT requests, and `public:delete` for DELETE requests.
        `public:delete` is only available together with `public:write`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.