Skip to main content
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 for a single user, with an optional event payload that flows into the template.
  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

Identify the user and event payload

The trigger endpoint fires a trigger-type campaign for one user at a time. The body has two required fields:To send to multiple users, call the endpoint once per user (typically from your queue/worker layer).
3

Trigger the send

On success the response is { "success": true } and the send is enqueued for the standard delivery lifecycle.
4

Track delivery downstream

Once enqueued, a campaign send progresses through the standard delivery lifecycle. Watch progress on the campaign detail page in the Spotzee app, where send, delivery, and engagement counts update in real time. Enterprise high-deliverability projects can also forward enabled delivery events from Settings → Webhook Endpoints.

​
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 user attributes ({{user.…}}) and the event payload ({{event.…}}). Anything not in either shows up as blank.
  • Don’t trigger in a tight loop without batching. Each call fires one send for one user; if you’re sending to a large audience, queue and pace the calls (or use a blast-type campaign against a list instead).

​
Reference