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

# Pause Campaign

> Stop a campaign that is `scheduled`, `compiling` or `sending`. It moves to `paused` with `pause_reason` `api` and `resume_at` null. Messages already handed off for delivery still arrive; nothing more is sent. The platform never resumes an `api` pause by itself: call `POST /email/campaigns/{id}/resume`.

A campaign that is already `paused` returns 200 with its current state, and keeps its own `pause_reason`, which may be a reason the platform set; that is how you learn why it stopped. Pausing an already paused campaign also cancels a planned resume (`resume_at` becomes null). Any other status (`draft`, `awaiting_test`, `awaiting_approval`, `ready`, `completed`) returns `409` `CONFLICT`. The body is optional and must be empty or `{}`; any field, including `reason`, returns `400` `VALIDATION_ERROR`, because the reason is always `api`. Pausing is not blocked when sending is suspended for the organization.

In a sequence, each email is its own campaign. Pausing an email holds the follow-ups after it: a follow-up whose time comes waits while the email before it is paused. A triggered campaign that is paused refuses `POST /email/campaigns/{id}/recipients` with `409` `CONFLICT` (start or resume it first); entries already queued wait, and resuming takes them again.



## OpenAPI

````yaml /api-reference/openapi.json post /email/campaigns/{id}/pause
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}/pause:
    post:
      tags:
        - Email Campaigns
      summary: Pause Campaign
      description: >-
        Stop a campaign that is `scheduled`, `compiling` or `sending`. It moves
        to `paused` with `pause_reason` `api` and `resume_at` null. Messages
        already handed off for delivery still arrive; nothing more is sent. The
        platform never resumes an `api` pause by itself: call `POST
        /email/campaigns/{id}/resume`.


        A campaign that is already `paused` returns 200 with its current state,
        and keeps its own `pause_reason`, which may be a reason the platform
        set; that is how you learn why it stopped. Pausing an already paused
        campaign also cancels a planned resume (`resume_at` becomes null). Any
        other status (`draft`, `awaiting_test`, `awaiting_approval`, `ready`,
        `completed`) returns `409` `CONFLICT`. The body is optional and must be
        empty or `{}`; any field, including `reason`, returns `400`
        `VALIDATION_ERROR`, because the reason is always `api`. Pausing is not
        blocked when sending is suspended for the organization.


        In a sequence, each email is its own campaign. Pausing an email holds
        the follow-ups after it: a follow-up whose time comes waits while the
        email before it is paused. A triggered campaign that is paused refuses
        `POST /email/campaigns/{id}/recipients` with `409` `CONFLICT` (start or
        resume it first); entries already queued wait, and resuming takes them
        again.
      operationId: pauseEmailCampaign
      parameters:
        - $ref: '#/components/parameters/IdPath'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
            example: {}
      responses:
        '200':
          description: Campaign paused, or already paused (current state returned).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaign'
                required:
                  - success
                  - data
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '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: >-
            The campaign is not in a pausable status (error code CONFLICT). Only
            `scheduled`, `compiling` and `sending` campaigns can be paused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notPausable:
                  summary: Campaign is still a draft
                  value:
                    error: A draft campaign cannot be paused
                    code: CONFLICT
        '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:
    EmailCampaign:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - draft
            - awaiting_test
            - awaiting_approval
            - ready
            - scheduled
            - compiling
            - sending
            - paused
            - completed
            - deleted
        type:
          type: string
          enum:
            - broadcast
            - triggered
          description: >-
            Fixed at creation. A `triggered` campaign has no `list_ids`; it
            sends to each person its `trigger` brings in. A campaign with
            follow-ups is a `broadcast`: see `sequence_id` and
            `sequence_position`.
        trigger:
          description: The trigger of a triggered campaign; `null` for a broadcast.
          oneOf:
            - $ref: '#/components/schemas/Trigger'
            - type: 'null'
        sender_identity_id:
          type: string
          format: uuid
        list_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Lists the campaign sends to. Empty when the campaign sends to tags
            only, or is triggered.
        suppression_list_ids:
          type: array
          items:
            type: string
            format: uuid
        tracking_domain_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Tracking domain serving this campaign's `/e/*` URLs. `null` means
            the platform link host.
        tracking_domain:
          type: object
          nullable: true
          description: >-
            The resolved tracking domain, returned on the single-campaign read.
            Links are branded only while `status` is `active`; any other status
            falls back to the platform link host for the send.
          properties:
            id:
              type: string
              format: uuid
            domain:
              type: string
            status:
              type: string
        require_approval:
          type: boolean
          description: >-
            Require an approval after the test send before this campaign can
            schedule or send. Off by default; every campaign still requires a
            successful test send regardless of this setting.
        approval_status:
          type: string
          enum:
            - not_required
            - pending
            - approved
          description: >-
            `not_required` when `require_approval` is off. `pending` once a
            current test send exists and approval is outstanding. `approved`
            once granted. Editing the campaign's content, sender, lists,
            suppression lists, or template resets a `pending` or `approved`
            status back to `pending` behind a new required test.
        last_tested_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the campaign's current test send completed. Null until a test
            send succeeds, and cleared whenever a later edit invalidates it.
        refcode:
          type:
            - string
            - 'null'
          description: >-
            Fundraising refcode appended to donation links for attribution.
            Generated as `e-` plus eight characters when omitted.
        source_code:
          type:
            - string
            - 'null'
        scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
        timezone:
          type:
            - string
            - 'null'
        sequence_send_time:
          type:
            - string
            - 'null'
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
          description: >-
            A triggered campaign's next-day send time, `HH:MM` in `timezone`;
            null otherwise.
        sequence_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The sequence this campaign belongs to; the first email's id, which
            points at itself. `null` for a campaign with no follow-ups.
        sequence_position:
          type:
            - integer
            - 'null'
          description: >-
            1 for the first email of a sequence, 2 and up for its follow-ups.
            `null` for a campaign with no follow-ups.
        stop_on_reply:
          type: boolean
          description: >-
            Campaigns with follow-ups only: replies come back through the
            platform, are forwarded to the sender's reply address, and end that
            person's follow-ups.
        stop_on_click:
          type: boolean
          description: >-
            Campaigns with follow-ups only: a click on a tracked link in any
            email of the campaign ends that person's follow-ups.
        audience_count:
          type:
            - integer
            - 'null'
          description: Deduplicated, suppression-filtered recipient count.
        counts:
          $ref: '#/components/schemas/EmailCampaignCounts'
        pause_reason:
          type:
            - string
            - 'null'
          description: >-
            Why the campaign is paused; null when not paused. `manual` (the
            dashboard) or `api` (`POST /email/campaigns/{id}/pause`) is a
            person's own pause and waits for `POST
            /email/campaigns/{id}/resume`. `insufficient_balance`,
            `insufficient_funds_ancestor`, `sender_inactive`, `no_content`,
            `tenant_paused` and `gmail_spam_rate` are set by the platform and
            clear on their own once the condition does (sending resumes without
            a call). Deliverability breakers no longer pause: a bounce trip
            drops the never-mailed tail and the campaign finishes; a second trip
            or a complaint trip finishes it (status `completed`).
            `provider_refused` is set by the platform when three batches in a
            row could not be handed off for delivery, usually because of a
            problem on the platform's side; nothing is charged for those batches
            and the recipients not yet sent to stay queued. It does not clear on
            its own: contact support, and resume the campaign with `POST
            /email/campaigns/{id}/resume` (or from the dashboard) once it is
            resolved. A resume clears any reason; if the cause still holds, the
            platform pauses the campaign again after one more refused batch.
        resume_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When a planned resume will happen, set by `POST
            /email/campaigns/{id}/resume` with a future `resume_at`; null
            otherwise. The campaign stays `paused` until then.
        blocked:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
            additionalProperties: true
          description: >-
            Returned by the single-campaign read only: the machine-readable
            reasons this campaign will not schedule yet. Empty when it is ready.
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        tag_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Tags whose subscribed addresses the campaign sends to (ANY), beside
            `list_ids`.
        require_tag_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Recipients must carry ALL of these tags.
        suppression_tag_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Addresses carrying any of these tags are skipped for this send.
      required:
        - id
        - name
        - status
        - sender_identity_id
      additionalProperties: true
    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).
    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.
    Trigger:
      description: >-
        What adds a recipient to a triggered project or email campaign, and when
        each one is sent. The same shape is used for text and email. `source`
        selects the variant: `api` (you or an inbound hook add recipients),
        `donation` (a gift from a connected WinRed or Anedot list), `event`
        (something that happens in another project or campaign), or `tag` (a
        contact was tagged). A text project listening to an email event, or the
        reverse, sends only when the contact record carries the other address.


        A person is sent a triggered project or campaign once. The `reentry`
        option was removed: `{"mode": "once"}` is still accepted and ignored, so
        a trigger read back from an older response can be sent as it is, and any
        other `reentry` value returns `400`. Responses never carry it. A second
        entry for the same person returns `200` `already_entered`.


        **When the first message goes.** `start` is `immediate` (the default:
        after `delay_minutes`) or `next_day`: the calendar day after the trigger
        fired, at the project's or campaign's own time of day in its own time
        zone. With `next_day`, `delay_minutes` must be 0. The time zone and time
        of day are fields beside the trigger, sent in the same request:
        `scheduled_timezone` and `sequence_send_time` on a project, `timezone`
        and `sequence_send_time` on an email campaign. For a text, the
        recipient's own quiet hours (8 AM to 10 PM local) can only move the send
        later.
      oneOf:
        - type: object
          title: api
          required:
            - source
          properties:
            source:
              type: string
              enum:
                - api
            start:
              type: string
              enum:
                - immediate
                - next_day
              default: immediate
              description: >-
                `immediate` sends after `delay_minutes`. `next_day` sends on the
                calendar day after the trigger fired, at `sequence_send_time` in
                the project's `scheduled_timezone` (email: `timezone`); both are
                required in the same write, and `delay_minutes` must be 0.
            delay_minutes:
              type: integer
              minimum: 0
              maximum: 43200
              default: 0
              description: >-
                Minutes to wait after the trigger fires before sending. A text
                that comes due between 10 PM and 8 AM in the recipient's time
                zone (by area code) is held until 8 AM; email has no such hold.
                Must be 0 when `start` is `next_day`.
          additionalProperties: false
        - type: object
          title: donation
          required:
            - source
            - donation
          properties:
            source:
              type: string
              enum:
                - donation
            donation:
              $ref: '#/components/schemas/TriggerDonation'
            start:
              type: string
              enum:
                - immediate
                - next_day
              default: immediate
              description: >-
                `immediate` sends after `delay_minutes`. `next_day` sends on the
                calendar day after the trigger fired, at `sequence_send_time` in
                the project's `scheduled_timezone` (email: `timezone`); both are
                required in the same write, and `delay_minutes` must be 0.
            delay_minutes:
              type: integer
              minimum: 0
              maximum: 43200
              default: 0
              description: >-
                Minutes to wait after the trigger fires before sending. A text
                that comes due between 10 PM and 8 AM in the recipient's time
                zone (by area code) is held until 8 AM; email has no such hold.
                Must be 0 when `start` is `next_day`.
          additionalProperties: false
        - type: object
          title: event
          required:
            - source
            - event
          properties:
            source:
              type: string
              enum:
                - event
            event:
              $ref: '#/components/schemas/TriggerEvent'
            start:
              type: string
              enum:
                - immediate
                - next_day
              default: immediate
              description: >-
                `immediate` sends after `delay_minutes`. `next_day` sends on the
                calendar day after the trigger fired, at `sequence_send_time` in
                the project's `scheduled_timezone` (email: `timezone`); both are
                required in the same write, and `delay_minutes` must be 0.
            delay_minutes:
              type: integer
              minimum: 0
              maximum: 43200
              default: 0
              description: >-
                Minutes to wait after the trigger fires before sending. A text
                that comes due between 10 PM and 8 AM in the recipient's time
                zone (by area code) is held until 8 AM; email has no such hold.
                Must be 0 when `start` is `next_day`.
          additionalProperties: false
        - type: object
          title: tag
          required:
            - source
            - tag
          properties:
            source:
              type: string
              enum:
                - tag
            tag:
              $ref: '#/components/schemas/TriggerTag'
            start:
              type: string
              enum:
                - immediate
                - next_day
              default: immediate
              description: >-
                `immediate` sends after `delay_minutes`. `next_day` sends on the
                calendar day after the trigger fired, at `sequence_send_time` in
                the project's `scheduled_timezone` (email: `timezone`); both are
                required in the same write, and `delay_minutes` must be 0.
            delay_minutes:
              type: integer
              minimum: 0
              maximum: 43200
              default: 0
              description: >-
                Minutes to wait after the trigger fires before sending. A text
                that comes due between 10 PM and 8 AM in the recipient's time
                zone (by area code) is held until 8 AM; email has no such hold.
                Must be 0 when `start` is `next_day`.
          additionalProperties: false
      discriminator:
        propertyName: source
    EmailCampaignCounts:
      type: object
      properties:
        queued:
          type: integer
        sent:
          type: integer
        delivered:
          type: integer
        bounced:
          type: integer
        complained:
          type: integer
        unsubscribed:
          type: integer
        opened:
          type: integer
        clicked:
          type: integer
        replied:
          type: integer
          description: Replies to a sequence email that came back through the platform.
        failed:
          type: integer
      additionalProperties: true
    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
    TriggerDonation:
      type: object
      required:
        - integrations
      description: Which donations fire the trigger. Every filter you set must match.
      properties:
        integrations:
          type: array
          minItems: 1
          maxItems: 20
          description: The connected donation integrations to listen to.
          items:
            type: object
            required:
              - provider
              - id
            properties:
              provider:
                type: string
                enum:
                  - winred
                  - anedot
              id:
                type: string
                format: uuid
                description: The integration id.
        donor:
          type: string
          enum:
            - any
            - first_time
            - returning
          default: any
          description: >-
            `first_time` matches a donor with no earlier gift on record for your
            organization; `returning` matches everyone else.
        gift:
          type: string
          enum:
            - any
            - one_time
            - recurring
          default: any
        amount_min:
          type:
            - number
            - 'null'
          description: Smallest gift in dollars, inclusive. `null` for no minimum.
        amount_max:
          type:
            - number
            - 'null'
          description: Largest gift in dollars, inclusive. `null` for no maximum.
        page_names:
          type: array
          items:
            type: string
          description: >-
            Donation page names to match, case-insensitive and exact. Empty
            matches any page.
        source_codes:
          type: array
          items:
            type: string
          description: >-
            Source codes to match, case-insensitive and exact. Empty matches any
            code.
      additionalProperties: false
    TriggerEvent:
      type: object
      required:
        - event
      description: Which event, in which projects or campaigns, fires the trigger.
      properties:
        event:
          type: string
          enum:
            - text_link_click
            - text_reply
            - email_open
            - email_click
            - email_reply
          description: >-
            Email opens are approximate: some mail apps hide them, so an open is
            not a count of readers.
        sources:
          description: >-
            `any` listens to every project (for a text event) or campaign (for
            an email event) in your organization except other triggered ones. Or
            name the ones to listen to: project ids for `text_*` events,
            campaign ids for `email_*` events.
          default: any
          oneOf:
            - type: string
              enum:
                - any
            - type: object
              required:
                - ids
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    format: uuid
              additionalProperties: false
        link_url:
          type: string
          format: uri
          description: 'Only for `email_click`: fire only when the clicked link is this URL.'
      additionalProperties: false
    TriggerTag:
      type: object
      required:
        - tag_ids
      description: >-
        Which tags fire the trigger: it fires when a contact is tagged with any
        of them. The tags must be your organization's own manual tags (an
        activity tag, or a tag of another organization, returns `400` at
        `trigger.tag.tag_ids.<index>`). A tagged phone number triggers a text
        project and a tagged email address triggers an email campaign. Tagging a
        contact who already has the tag never fires it, and a person is sent a
        triggered project or campaign once, so removing and re-adding the tag
        does not send again. Who is texted: a tagged phone number on a list the
        project can use is texted with that list row's merge fields; one on no
        list at all is texted with merge-field defaults; one whose only list
        rows belong to another brand, toll-free number or short code is not
        texted, is counted in the project's report, and has not used its one
        entry. Opted-out numbers are never sent to. The tags are chosen before
        the project or campaign starts: once it has started, a `trigger` that
        changes its tags (or turns another kind of trigger into a tag trigger,
        or the reverse) returns `400`. At its first start a tag trigger asks who
        it sends to: see `audience` on `POST /projects/{id}/start` and `POST
        /email/campaigns/{id}/schedule`.
      properties:
        tag_ids:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            format: uuid
          description: One to 20 distinct tag ids, from `GET /tags`.
      additionalProperties: false
  responses:
    BadRequest:
      description: >-
        Invalid request (validation failure, malformed parameters, or a request
        the resource state does not allow).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Validation failed
            code: VALIDATION_ERROR
            correlationId: 030bf857-922f-4b82-8fca-c5b0769c1590
            details:
              - field: organization_id
                message: Invalid UUID
                code: invalid_format
    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.