Trigger a one-off campaign

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:

Looks up an existing campaign by ID.
Triggers a send for a single contact, with an optional event payload that flows into the template.
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. This procedure triggers an existing campaign; creating a campaign is a separate API operation.

Walkthrough

Find the campaign ID

GET /campaigns?limit=100 returns up to 100 campaigns with their identifiers. Follow pagination to inspect further campaigns. In production, store the IDs you need in your config rather than looking them up on every send.Use the campaign prepared for this per-contact trigger. Scheduling a blast campaign is a different operation and requires its audience and send-time configuration.

Identify the contact and event payload

The trigger endpoint queues a campaign send for one contact at a time. Acceptance does not confirm delivery; recipient eligibility and subscription checks run during processing. The body has two required fields:

Field	Shape	Notes
`user`	object	Identifies the contact. `external_id` is required; `email`, `phone`, `device_token`, `timezone`, `locale` are optional, and any additional custom attributes you include flow through to the contact record.
`event`	object	Free-form JSON, exposed to the campaign template as `{{event}}` (so `{{event.order_id}}` etc. resolve as template variables). May be `{}` if your template doesn’t reference event data.

To send to multiple contacts, call the endpoint once per contact (typically from your queue/worker layer).

Trigger the send

POST /api/client/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

{
  "user": {
    "external_id": "cust_001",
    "email": "ada@example.com",
    "first_name": "Ada"
  },
  "event": {
    "order_id": "12345",
    "total": 99.99
  }
}

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

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 message outcomes and engagement counts update after processing. Enterprise high-deliverability projects can also forward enabled delivery events from Settings → Webhook Endpoints.

Pitfalls to avoid

Use a triggered campaign for a single per-contact message. Use a journey when you need several steps, waits, or branches. See Trigger a journey.

Prevent duplicate logical triggers. Keep a stable request identity and check whether a timed-out call was accepted before retrying. An Idempotency-Key protects retries only where enforcement is enabled; see Idempotency.
Don’t expect templates to render with arbitrary data. Template variables resolve against the contact 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 contact; if you’re sending to a large audience, queue and pace the calls (or use a blast-type campaign against a list instead).

Reference

API surface: see Main API → Campaigns
Safe retries: see Idempotency
Per-event automation instead: see Trigger a journey

Get started

Build

Configure

SDKs

Integrate

Reporting

Tools

API conventions

Recipes

Trigger a one-off campaign

What you’ll build

Prerequisites

Walkthrough

Pitfalls to avoid

Reference

​What you’ll build

​Prerequisites

​Walkthrough

​Pitfalls to avoid

​Reference

What you’ll build

Prerequisites

Walkthrough

Pitfalls to avoid

Reference