Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

Use this flow when you’ve already authored a campaign in the Spotzee UI (audience, template, send-time settings) and want to fire it on demand from your code — for example, the morning of a product launch or in response to a webhook from another system.

​
What you’ll build

A backend call that:
  1. Looks up an existing campaign by ID.
  2. Triggers a send with one or more contacts as the recipient set.
  3. Captures the response so you can correlate the send with downstream delivery events.

​
Prerequisites

You’ll need a sk_ project key. The campaign must already exist in Spotzee — the API triggers existing campaigns rather than authoring new ones from scratch.

​
Walkthrough

1

Find the campaign ID

GET /campaigns?limit=100 returns every campaign in the project with its id. In production, store the IDs you need in your config rather than looking them up on every send.A campaign in state: "draft" cannot be triggered. Promote it via the UI, or PATCH /campaigns/{id} to set state: "scheduled".
2

Decide on the recipient set

Two shapes are supported:
ShapeUse when
Audience already on the campaignThe campaign is already targeted at a list or segment — just trigger it
Per-call recipientsYou want to fire the same template at a one-off list of contacts (for example, a transactional broadcast keyed on a user action)
The per-call form passes a users array. Each entry can be { external_id }, { anonymous_id }, or { email }. Custom attributes available to the template can ride alongside.
3

Trigger the send

POST /campaigns/{campaignId}/trigger HTTP/1.1
Host: apix.spotzee.com
Authorization: Bearer sk_…
Idempotency-Key: launch-2026-04-28
Spotzee-Version: 2026-04-28
Content-Type: application/json

{
  "users": [
    { "external_id": "cust_001", "first_name": "Ada" },
    { "external_id": "cust_002", "first_name": "Grace" }
  ]
}
The response confirms how many recipients were enqueued and returns a per-user error array for any rejected entries.
4

Track delivery downstream

Once enqueued, a campaign send progresses through the standard delivery lifecycle. Configure a webhook endpoint to receive message.sent, message.delivered, message.bounced, and message.opened events tied back to the campaign and recipient.

​
Pitfalls to avoid

Don’t reuse a campaign as a transactional template. Campaigns are designed for one-shot sends to a stable audience. For per-event transactional messages (welcome emails, password resets, receipt confirmations), trigger a journey instead — see Trigger a journey.
  • Don’t trigger the same campaign twice in a row. Spotzee will happily send twice — that’s what the API is for. Use an Idempotency-Key so a network retry doesn’t double-send. See Idempotency.
  • Don’t expect templates to render with arbitrary data. Template variables resolve against the contact + the per-call attributes you passed. Anything not in either shows up as blank.
  • Don’t trigger campaigns in a tight loop. A single trigger can target thousands of recipients; reach for the per-call audience approach rather than calling trigger N times.

​
Reference