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

# List campaign messages

> Returns one row per sent or scheduled message, including repeated messages to the same contact. Sorts by send time with user and reference identifiers as tie-breakers.



## OpenAPI

````yaml https://apix.spotzee.com/api/openapi.json get /campaigns/{campaignId}/recipients
openapi: 3.1.0
info:
  title: Spotzee API
  version: '2026-04-28'
  description: >-
    Programmatic access to Spotzee. Use this API to manage users, lists,
    segments, campaigns, journeys, templates, and events from your own systems.
  contact:
    name: Spotzee Support
    url: https://docs.spotzee.com
  license:
    name: Proprietary
    url: https://docs.spotzee.com/
servers:
  - url: https://apix.spotzee.com/api
    description: >-
      Public unauthenticated surface — used for form-token submissions and other
      token-scoped callbacks.
  - url: https://apix.spotzee.com/api/client
    description: >-
      Project-scoped surface — use with `sk_` (secret) or `pk_` (publishable)
      API keys.
  - url: https://apix.spotzee.com/api/admin
    description: >-
      Organisation-scoped surface — use with `ok_` API keys for cross-project
      administration.
security: []
tags:
  - name: Projects
    description: >-
      The project the calling key belongs to. Read-only on the project surface —
      use organisation-level keys for project lifecycle.
  - name: Users
    description: >-
      People you message. Identify each one by your own `external_id`; attach
      any custom attributes you want to segment on.
  - name: Events
    description: >-
      Behavioural signals from your application. Drive trigger campaigns and
      journeys, enrich segments, and personalise message content.
  - name: Form submissions
    description: >-
      Token-scoped website form submissions. Use generated form URLs for
      browser-safe opt-ins without exposing secret API keys.
  - name: Lists
    description: >-
      Static and dynamic groups of users. Static lists are explicit memberships;
      dynamic lists evaluate their current membership rule when queried.
  - name: Subscriptions
    description: >-
      Channel-level opt-in state per user. Each subscription type maps to a
      channel (email, push, SMS, webhook, in-app).
  - name: Templates
    description: >-
      Channel-specific message bodies with Handlebars personalisation. Preview,
      proof, and version each template independently.
  - name: Campaigns
    description: >-
      One-off `blast` sends and per-user `trigger` sends. Each campaign targets
      one channel and one subscription type.
  - name: CRM
    description: >-
      Customer relationship records for contacts, companies, pipeline stages,
      activities, and saved views within the calling project.
  - name: Source Sync
    description: >-
      Sync contacts, companies, source-managed CRM properties, and company
      memberships from your own backend systems into the calling project.
  - name: Journeys
    description: >-
      Multi-step automation flows triggered by events, list memberships, or
      campaign sends. Branch on attributes, wait between steps, and send across
      channels.
  - name: Tags
    description: >-
      Free-form labels you can attach to campaigns, journeys, lists, and
      templates for organisation and bulk filtering.
  - name: API keys
    description: >-
      Project-scoped credentials. Create, list, and revoke `sk_` and `pk_` keys
      for the project the calling key belongs to.
  - name: Organisation
    description: >-
      Organisation-scoped operations. Use with `ok_` keys to manage projects
      across an organisation, including the org-level API key catalogue.
  - name: Webhooks
    description: >-
      Outgoing event delivery. Configure HTTPS endpoints, choose events, and
      verify inbound deliveries with the `Spotzee-Signature` HMAC header.
paths:
  /campaigns/{campaignId}/recipients:
    get:
      tags:
        - Campaigns
      summary: List campaign messages
      description: >-
        Returns one row per sent or scheduled message, including repeated
        messages to the same contact. Sorts by send time with user and reference
        identifiers as tie-breakers.
      operationId: listCampaignRecipients
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Numeric campaign identifier.
            example: 24
          required: true
          description: Numeric campaign identifier.
          name: campaignId
          in: path
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          required: false
          name: limit
          in: query
        - schema:
            $ref: '#/components/schemas/BounceCategory'
          required: false
          description: >-
            Diagnostic cause identifier. The UI labels unknown as Unclassified
            and dns_routing_error as DNS or routing error. Unknown is the
            fallback when evidence does not establish a cause.
          name: bounce_category
          in: query
        - schema:
            type: string
            enum:
              - all
              - sent
              - opened
              - bounced
            default: all
          required: false
          name: segment
          in: query
        - schema:
            type: string
            enum:
              - send_at
            default: send_at
          required: false
          name: sort
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          required: false
          name: direction
          in: query
        - schema:
            type: string
            maxLength: 2048
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: A bounded page of campaign messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignRecipientsPage'
        '400':
          description: Malformed request — bad parameters, body, or version header.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required or the supplied API key is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Authenticated, but the credential lacks scope or role for this
            resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The referenced resource does not exist or is not visible to this
            key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — duplicate resource or idempotency-key body mismatch.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request was syntactically valid but semantically rejected (failed
            validation).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limit bucket exhausted. Honour `Retry-After`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unhandled server error. `request_id` should be reported to support.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - projectApiKey: []
      servers:
        - url: https://apix.spotzee.com/api/client
components:
  schemas:
    BounceCategory:
      type: string
      enum:
        - invalid_recipient
        - mailbox_unavailable
        - mailbox_full
        - authentication_failed
        - policy_blocked
        - spam_rejected
        - reputation_blocked
        - rate_limited
        - content_rejected
        - dns_routing_error
        - transport_error
        - unknown
      description: >-
        Diagnostic cause identifier. The UI labels unknown as Unclassified and
        dns_routing_error as DNS or routing error. Unknown is the fallback when
        evidence does not establish a cause.
    CampaignRecipientsPage:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CampaignRecipient'
        next:
          type:
            - string
            - 'null'
        prev:
          type:
            - string
            - 'null'
        limit:
          type: integer
      required:
        - results
        - next
        - prev
        - limit
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
          description: Constant marker indicating this payload is an error response.
        code:
          $ref: '#/components/schemas/ErrorCode'
        title:
          type: string
          description: Short, human-readable summary suitable for a heading. en-AU.
          example: Resource missing
        message:
          type: string
          description: Human-readable, en-AU explanation. May include identifiers.
          example: User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.
        error:
          type: string
          description: >-
            Legacy human-readable mirror of `message`. Retained while in-product
            clients migrate; new integrations should read `message`.
        type:
          type: string
          format: uri
          description: Documentation URL for this error class (RFC 7807).
          example: https://docs.spotzee.com/main-api/errors#resource_missing
        request_id:
          type: string
          description: >-
            Server-generated correlation ID. Echoed in the X-Request-ID response
            header.
          example: req_01HXY7Z9K8M5J2N4P6Q8R0S1T2
        param:
          type: string
          description: Name of the offending parameter, when a single field is at fault.
          example: id
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: Field-level errors when multiple parameters fail validation.
      required:
        - status
        - code
        - message
        - error
      description: >-
        Spotzee error envelope (RFC 7807 + Stripe-style extensions). Served as
        `application/problem+json`.
    CampaignRecipient:
      type: object
      properties:
        id:
          type: string
        campaign_id:
          type: integer
        user_id:
          type: integer
        reference_id:
          type: string
        email:
          type:
            - string
            - 'null'
          description: >-
            Email used for this send; null when no original destination is
            recorded.
        phone:
          type:
            - string
            - 'null'
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
          enum:
            - pending
            - sent
            - throttled
            - failed
            - bounced
            - aborted
        send_at:
          type:
            - string
            - 'null'
        opened_at:
          type:
            - string
            - 'null'
        clicks:
          type: integer
        bounce_category:
          allOf:
            - $ref: '#/components/schemas/BounceCategory'
            - type:
                - string
                - 'null'
        bounce_classification:
          allOf:
            - $ref: '#/components/schemas/BounceClassification'
            - type:
                - object
                - 'null'
              description: >-
                Diagnostic cause, severity and finality. Unknown means the
                retained evidence does not establish a cause; reason explains
                why. Diagnostic text is untrusted and must be escaped when
                rendered.
      required:
        - id
        - campaign_id
        - user_id
        - reference_id
        - email
        - phone
        - first_name
        - last_name
        - state
        - send_at
        - opened_at
        - clicks
        - bounce_category
        - bounce_classification
      additionalProperties: false
    ErrorCode:
      type: string
      enum:
        - resource_missing
        - resource_already_exists
        - state_conflict
        - archived_user_conflict
        - user_capacity_exhausted
        - parameter_missing
        - parameter_invalid_empty
        - parameter_invalid_format
        - parameter_unknown
        - validation_failed
        - authentication_required
        - permission_denied
        - idempotency_key_mismatch
        - idempotency_key_invalid
        - idempotency_in_progress
        - rate_limited
        - version_unsupported
        - version_required
        - webhook_signature_invalid
        - quota_exceeded
        - service_unavailable
        - internal_error
      description: Stable, machine-readable error code. Safe to switch on; never localised.
      example: resource_missing
    FieldError:
      type: object
      properties:
        param:
          type: string
          description: Dotted path to the offending request field.
          example: email
        code:
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
            - description: Per-field error code.
              example: parameter_invalid_format
        message:
          type: string
          description: Human-readable, English (en-AU) explanation of this field error.
          example: Must be a valid email address.
      required:
        - param
        - code
        - message
    BounceClassification:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/BounceCategory'
        severity:
          type: string
          enum:
            - temporary
            - permanent
            - unknown
          description: >-
            Severity of the diagnostic evidence, independent of finality. A
            temporary diagnostic can accompany a final outcome.
        final:
          type: boolean
          description: >-
            Whether this event establishes a delivery-final failure. A temporary
            code without retry-exhaustion proof is non-final, even if the
            original sending process stopped. False also includes unconfirmed
            outcomes; it does not establish successful delivery or promise an
            automatic retry.
        diagnostic:
          type: string
          maxLength: 2048
        ruleset:
          type: string
        rule_id:
          type:
            - string
            - 'null'
        source_evidence:
          type: object
          additionalProperties:
            type: string
        classified_at:
          type: string
          format: date-time
          description: >-
            When the classification was produced; not the event occurrence time
            or report freshness timestamp.
        reason:
          type: string
          enum:
            - matched
            - unmatched
            - missing_evidence
            - ambiguous
            - not_a_bounce
          description: >-
            Why the diagnostic matched a cause or remained unknown. Missing,
            unmatched and ambiguous evidence must not be treated as delivery
            success.
      required:
        - category
        - severity
        - final
        - diagnostic
        - ruleset
        - rule_id
        - source_evidence
        - classified_at
        - reason
      additionalProperties: false
      description: >-
        Present only when `include_bounce_classification=true`. The `unknown`
        category is shown as Unclassified; severity and finality do not imply
        inbox placement.
  securitySchemes:
    projectApiKey:
      type: http
      scheme: bearer
      description: >-
        Project-scoped secret API key (`sk_…`). Pass in the `Authorization:
        Bearer <key>` header. Grants access to the project the key was issued
        for.

````

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