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

# Create a campaign

> Creates a new campaign. To schedule a blast send, follow up with `PATCH /:campaignId` setting `state: "scheduled"` and `send_at`.

Idempotent — pass an `Idempotency-Key` header to make safely retryable. On a replay the original response is returned with `Idempotent-Replayed: true`. See the API conventions guide for the full state machine, TTL, and mismatch behaviour.



## OpenAPI

````yaml https://apix.spotzee.com/api/openapi.json post /campaigns
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:
    post:
      tags:
        - Campaigns
      summary: Create a campaign
      description: >-
        Creates a new campaign. To schedule a blast send, follow up with `PATCH
        /:campaignId` setting `state: "scheduled"` and `send_at`.


        Idempotent — pass an `Idempotency-Key` header to make safely retryable.
        On a replay the original response is returned with `Idempotent-Replayed:
        true`. See the API conventions guide for the full state machine, TTL,
        and mismatch behaviour.
      operationId: createCampaign
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '200':
          description: The newly created campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '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:
    CampaignCreate:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CampaignType'
        name:
          type: string
          minLength: 1
        channel:
          $ref: '#/components/schemas/CampaignChannel'
        subscription_id:
          type: integer
        provider_id:
          type: integer
        list_ids:
          type:
            - array
            - 'null'
          items:
            type: integer
        exclusion_list_ids:
          type:
            - array
            - 'null'
          items:
            type: integer
        send_in_user_timezone:
          type:
            - boolean
            - 'null'
        send_at:
          type:
            - string
            - 'null'
          format: date-time
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        custom_domain_id:
          type:
            - integer
            - 'null'
        description:
          type:
            - string
            - 'null'
      required:
        - type
        - subscription_id
        - provider_id
      description: >-
        Create a new campaign. Subscription, provider, and target lists are
        required to send.
    Campaign:
      type: object
      properties:
        id:
          type: integer
          description: Numeric campaign identifier.
          example: 24
        project_id:
          type: integer
        type:
          $ref: '#/components/schemas/CampaignType'
        name:
          type: string
        list_ids:
          type:
            - array
            - 'null'
          items:
            type: integer
          description: IDs of the lists targeted by the campaign.
        exclusion_list_ids:
          type:
            - array
            - 'null'
          items:
            type: integer
          description: IDs of lists whose members should be excluded from the campaign.
        channel:
          $ref: '#/components/schemas/CampaignChannel'
        subscription_id:
          type: integer
          description: >-
            Subscription type a user must be opted in to in order to receive
            this campaign.
        subscription:
          $ref: '#/components/schemas/Subscription'
        provider_id:
          type: integer
          description: Delivery provider used to send the campaign.
        provider:
          $ref: '#/components/schemas/Provider'
        state:
          $ref: '#/components/schemas/CampaignState'
        delivery:
          $ref: '#/components/schemas/CampaignDelivery'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        send_in_user_timezone:
          type:
            - boolean
            - 'null'
          description: >-
            When true, `send_at` is interpreted as a wall-clock time in each
            user’s local timezone.
        send_at:
          anyOf:
            - type: string
            - type:
                - string
                - 'null'
            - type: 'null'
          description: When the campaign should send. ISO 8601 string accepted on input.
        custom_domain_id:
          type:
            - integer
            - 'null'
          description: >-
            Optional override of the project’s default tracking and from-address
            domain.
        created_by:
          type:
            - integer
            - 'null'
          description: >-
            Admin who created the campaign. Null for system- or API-key-created
            campaigns.
        created_by_admin:
          $ref: '#/components/schemas/CampaignCreatedByAdmin'
        description:
          type:
            - string
            - 'null'
          description: >-
            Internal-only description for the audit trail. Never shown to
            recipients.
        created_at:
          type:
            - string
            - 'null'
        updated_at:
          type:
            - string
            - 'null'
      required:
        - id
        - project_id
        - type
        - name
        - channel
        - subscription_id
        - provider_id
        - state
        - created_at
        - updated_at
      description: A one-off (`blast`) or per-user (`trigger`) send across one channel.
    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`.
    CampaignType:
      type: string
      enum:
        - blast
        - trigger
      description: >-
        `blast` campaigns send to every user in the target lists. `trigger`
        campaigns fire per-user when an event matches.
    CampaignChannel:
      type: string
      enum:
        - email
        - text
        - push
        - webhook
        - in_app
      description: Delivery channel the campaign sends through.
    Subscription:
      type: object
      properties:
        id:
          type: integer
          description: Numeric subscription-type identifier.
          example: 7
        project_id:
          type: integer
          description: Identifier of the owning project.
          example: 42
        name:
          type: string
          description: Human-readable subscription-type name shown on preference centres.
          example: Weekly newsletter
        channel:
          $ref: '#/components/schemas/SubscriptionChannel'
        is_public:
          type: boolean
          description: >-
            Whether this subscription type is shown on customer-facing
            preference centres.
        created_at:
          type:
            - string
            - 'null'
          description: Time the subscription type was created. ISO 8601.
        updated_at:
          type:
            - string
            - 'null'
          description: Time the subscription type was last modified. ISO 8601.
      required:
        - id
        - project_id
        - name
        - channel
        - is_public
        - created_at
        - updated_at
      description: Hydrated subscription type referenced by `subscription_id`.
    Provider:
      type: object
      properties:
        id:
          type: integer
          description: Numeric provider identifier.
          example: 19
        project_id:
          type: integer
          description: Identifier of the owning project.
          example: 42
        type:
          type: string
          description: >-
            Provider type within its group — the exact identifier of the
            underlying integration.
          example: smtp
        name:
          type: string
          description: Human-readable provider name shown in dashboards.
          example: Primary transactional SMTP
        group:
          $ref: '#/components/schemas/ProviderGroup'
        is_default:
          type: boolean
          description: >-
            Whether this provider is the default for its group within the
            project.
        rate_limit:
          type: integer
          minimum: 0
          description: Maximum sends per `rate_interval`. Zero means unlimited.
          example: 0
        rate_interval:
          $ref: '#/components/schemas/ProviderRateInterval'
        created_at:
          type:
            - string
            - 'null'
          description: Time the provider was created. ISO 8601.
        updated_at:
          type:
            - string
            - 'null'
          description: Time the provider was last modified. ISO 8601.
        deleted_at:
          type:
            - string
            - 'null'
          description: Time the provider was soft-deleted, if applicable.
      required:
        - id
        - project_id
        - type
        - name
        - group
        - is_default
        - rate_limit
        - rate_interval
        - created_at
        - updated_at
      description: >-
        Hydrated delivery provider referenced by `provider_id`. Returned in the
        redacted public shape — see `Provider` schema. Credentials (`data`,
        `auth`, API keys, tokens) are NEVER included.
    CampaignState:
      type: string
      enum:
        - draft
        - scheduled
        - loading
        - running
        - finished
        - aborting
        - aborted
      description: >-
        Campaign lifecycle state. Set `state: "scheduled"` (with `send_at`) to
        send a blast; set `state: "aborted"` to cancel.
    CampaignDelivery:
      type: object
      properties:
        sent:
          type: integer
        total:
          type: integer
        opens:
          type: integer
        clicks:
          type: integer
        bounced:
          type: integer
        bounce_categories:
          type: object
          properties:
            invalid_recipient:
              type: integer
              minimum: 0
            mailbox_unavailable:
              type: integer
              minimum: 0
            mailbox_full:
              type: integer
              minimum: 0
            authentication_failed:
              type: integer
              minimum: 0
            policy_blocked:
              type: integer
              minimum: 0
            spam_rejected:
              type: integer
              minimum: 0
            reputation_blocked:
              type: integer
              minimum: 0
            rate_limited:
              type: integer
              minimum: 0
            content_rejected:
              type: integer
              minimum: 0
            dns_routing_error:
              type: integer
              minimum: 0
            transport_error:
              type: integer
              minimum: 0
            unknown:
              type: integer
              minimum: 0
          description: >-
            Bounce counts by stable cause identifier. `unknown` is displayed as
            Unclassified when evidence is missing, unmatched, or ambiguous.
            Counts reconcile to `bounced`.
        classification_coverage:
          type: object
          properties:
            classified:
              type: integer
              minimum: 0
            unclassified:
              type: integer
              minimum: 0
            total:
              type: integer
              minimum: 0
          required:
            - classified
            - unclassified
            - total
          description: Counts of classified and unclassified bounced messages.
        calculated_at:
          type: string
          format: date-time
      required:
        - sent
        - total
        - opens
        - clicks
      description: Aggregated delivery counters for the campaign.
    CampaignCreatedByAdmin:
      type:
        - object
        - 'null'
      properties:
        admin_id:
          type: integer
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
          format: email
      required:
        - admin_id
      description: >-
        Safe display details for `created_by`, or null when the creator is
        system/API-key-created or no longer belongs to the project.
    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
    SubscriptionChannel:
      type: string
      enum:
        - email
        - text
        - push
        - webhook
        - in_app
      description: Delivery channel a subscription type covers.
      example: email
    ProviderGroup:
      type: string
      enum:
        - email
        - text
        - push
        - webhook
        - analytics
      description: Channel family the provider belongs to.
      example: email
    ProviderRateInterval:
      type: string
      enum:
        - second
        - minute
        - hour
        - day
      description: Window over which `rate_limit` is counted.
      example: second
  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.