Campaigns and sequencing

Campaigns (multi-step sequences with schedules, exit conditions and per-campaign caps) are a platform feature you configure in the dashboard, or that we build for you as part of the done-for-you setup. There are no campaign REST objects in /v1. An earlier revision of these docs sketched campaign endpoints that never shipped; they are gone, and this page describes what to build instead.

Why there is no campaign API

A campaign is orchestration: who gets which message, when, and when to stop. Your system (a CRM, a sequencer, an agent) already owns that logic. What the API gives you is the two primitives orchestration actually needs, with all the deliverability machinery attached:

1. Paced sends. POST /v1/messages in drip mode inherits capacity caps, warm-up, quiet hours and human-like spacing. You decide what and roughly when; the platform decides the exact safe moment.
2. Signals back. Webhooks tell you what happened: message.sent, message.delivered, message.read, message.failed, message.received, contact.opted_out.

The sequence pattern

A three-step follow-up sequence over the API:

1. Step send. Drip-send step 1 with an Idempotency-Key derived from your own sequence-step id, and your CRM id in metadata.
2. Listen. On message.received for that contact, mark the sequence replied and stop it. This is the exit condition that matters; on iMessage, reply rates make it the common exit.
3. Advance. No reply after your chosen delay: drip-send step 2. The delay_minutes field covers same-day pacing; multi-day steps are your scheduler's job.
4. Stop conditions. Stop on contact.opted_out always. Consider stopping on message.failed twice in a row, which usually means the number is dead.

Because drip sends are capacity-aware, a sequence that tries to start more new conversations than your lines can safely absorb queues rather than burns: the excess simply schedules later. Watch available_today on GET /v1/devices if you want to see headroom before pushing a batch.

Where the platform campaign feature fits

If you would rather not run orchestration at all, the platform's own campaign engine does structured sequences with per-campaign daily limits, and both limits (campaign and line) are enforced independently. Ask us to set it up during onboarding. Everything it sends is visible to the API afterwards: history in GET /v1/conversations, events on your webhooks.