politicalcomms-com Email Campaigns API

openapi: 3.2.0
info:
  title: Political Comms Email Campaigns 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), Conversations (read inbound threads and reply inside them), Contact Lists (S3 import and analysis), Media Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains, 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. 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.'
  version: 1.4.1
  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: 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.
paths:
  /email/campaigns:
    get:
      tags:
      - Email Campaigns
      summary: List Campaigns
      description: List email campaigns.
      operationId: listEmailCampaigns
      parameters:
      - $ref: '#/components/parameters/EmailLimit'
      - $ref: '#/components/parameters/EmailCursor'
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - draft
          - awaiting_test
          - awaiting_approval
          - ready
          - scheduled
          - compiling
          - sending
          - paused
          - completed
          - deleted
      - $ref: '#/components/parameters/EmailSearch'
      responses:
        '200':
          description: A page of campaigns.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/EmailCampaign'
                      has_more:
                        type: boolean
                      next_cursor:
                        type:
                        - string
                        - 'null'
                    required:
                    - data
                    - has_more
                    - next_cursor
                    additionalProperties: true
                required:
                - success
                - data
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Email Campaigns
      summary: Create Campaign
      description: Create a draft campaign.
      operationId: createEmailCampaign
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                sender_identity_id:
                  type: string
                  format: uuid
                list_ids:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                    format: uuid
                suppression_list_ids:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    format: uuid
                template_id:
                  type: string
                  format: uuid
                subject:
                  type: string
                  maxLength: 255
                preheader:
                  type: string
                  maxLength: 255
                html:
                  type: string
                  maxLength: 1000000
                source_code:
                  type: string
                  maxLength: 255
                refcode:
                  type: string
                  maxLength: 255
                append_utm:
                  type: boolean
                  description: Append UTM parameters to outbound links for attribution.
                is_repermission:
                  type: boolean
                  description: Mark the send as a re-permission (re-consent) message.
                tracking_domain_id:
                  type: string
                  format: uuid
                  nullable: true
                  description: Tracking domain serving this campaign's tracked links, open pixel, unsubscribe page and browser view, so recipients see your own `links.` host instead of the platform one. Must be an active tracking domain your organization owns or inherits from a parent. Omit to let the platform pick the obvious default (the tracking domain matching your sending domain's root, or your only one); send `null` to force the platform link host.
                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.
              required:
              - name
              - sender_identity_id
              - list_ids
              additionalProperties: true
            example:
              name: August appeal
              sender_identity_id: 3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42
              list_ids:
              - 7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64
              subject: Can you help before Friday?
              append_utm: true
      responses:
        '201':
          description: Campaign created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaign'
                required:
                - success
                - data
                additionalProperties: true
        '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, the organization has not completed required onboarding, 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:read'
                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
                onboardingIncomplete:
                  summary: Organization has not completed required onboarding (business profile or funding)
                  value:
                    error: Complete your account setup to continue
                    code: ONBOARDING_INCOMPLETE
                    details:
                      missingSteps:
                      - profile
                      - funding
                      onboardingUrl: /onboarding
                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'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '400':
          $ref: '#/components/responses/BadRequest'
  /email/campaigns/{id}:
    get:
      tags:
      - Email Campaigns
      summary: Get Campaign
      description: 'Fetch one campaign. This read additionally returns `blocked`: the machine-readable list of reasons the campaign will not schedule yet. Check it before calling schedule.'
      operationId: getEmailCampaign
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The campaign.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaign'
                required:
                - success
                - data
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /email/campaigns/{id}/schedule:
    post:
      tags:
      - Email Campaigns
      summary: Schedule Campaign
      description: Schedule the campaign, or omit `scheduled_at` to send now. A date in the past returns `400 VALIDATION_ERROR`. Scheduling runs the full checklist; if it refuses, read `blocked` on the campaign to see why.
      operationId: scheduleEmailCampaign
      parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scheduled_at:
                  type: string
                  format: date-time
                  description: Omit to send immediately.
              additionalProperties: true
            example:
              scheduled_at: '2026-09-05T15:00:00Z'
      responses:
        '200':
          description: Campaign scheduled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaign'
                required:
                - success
                - data
                additionalProperties: true
        '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:read'
                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
        '409':
          description: Sending is paused for the organization or platform-wide. Error code SENDING_PAUSED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                organizationPaused:
                  summary: Sending is paused for this organization
                  value:
                    error: Sending is currently paused for this organization
                    code: SENDING_PAUSED
                    details:
                      scope: organization
                platformPaused:
                  summary: Sending is paused platform-wide
                  value:
                    error: Sending is currently paused
                    code: SENDING_PAUSED
                    details:
                      scope: platform
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '400':
          $ref: '#/components/responses/BadRequest'
  /email/campaigns/{id}/unschedule:
    post:
      tags:
      - Email Campaigns
      summary: Unschedule Campaign
      description: Return a scheduled campaign to a draft state.
      operationId: unscheduleEmailCampaign
      parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      responses:
        '200':
          description: Campaign unscheduled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaign'
                required:
                - success
                - data
                additionalProperties: true
        '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:read'
                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'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '400':
          $ref: '#/components/responses/BadRequest'
  /email/campaigns/{id}/stats:
    get:
      tags:
      - Email Campaigns
      summary: Get Campaign Stats
      description: Report tiles, fundraising totals, and per-link click stats for a campaign. Cached for 60 seconds. Test and seed sends are excluded from every figure.
      operationId: getEmailCampaignStats
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Campaign stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/EmailCampaignStats'
                required:
                - success
                - data
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    Forbidden:
      description: The API key lacks the required permission scope, or the requested resource belongs to an organization outside the key's hierarchy.
      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:read'
            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
    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
    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
    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
    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
  schemas:
    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
    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
        failed:
          type: integer
      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).
    EmailCampaignStats:
      type: object
      properties:
        campaign_id:
          type: string
          format: uuid
        status:
          type: string
        tiles:
          type: object
          properties: {}
          description: 'Headline report tiles: sent, delivered, bounced, openRate, clickRate, actualCost.'
          additionalProperties: true
        links:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              url:
                type: string
              label:
                type:
                - string
                - 'null'
              is_donation_link:
                type: boolean
              clicks:
                type: integer
              unique_clicks:
                type: integer
            additionalProperties: true
        excludes_test_and_seed:
          type: boolean
          description: 'Always true: test sends and seed addresses are excluded from every figure here. Note that they are still billed.'
      description: Cached for 60 seconds.
      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.
    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
        sender_identity_id:
          type: string
          format: uuid
        list_ids:
          type: array
          items:
            type: string
            format: uuid
        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'
        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. A deliverability breaker sets this automatically.
        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
      required:
      - id
      - name
      - status
      - sender_identity_id
      additionalProperties: true
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: Resource ID
      schema:
        type: string
    EmailCursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor from the previous page's `next_cursor`.
      schema:
        type: string
        maxLength: 4096
    EmailSearch:
      name: search
      in: query
      required: false
      description: Case-insensitive substring match.
      schema:
        type: string
        maxLength: 255
    EmailLimit:
      name: limit
      in: query
      required: false
      description: Rows per page, 1-200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    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.'
  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.