Skip to main content
Campaign lifecycle calls are state transitions. Keep the campaign in draft until its audience, workflow, channels, and send windows have been reviewed.
  1. Create a campaign with POST /api/v1/public/campaigns.
  2. Configure the workflow with PATCH /api/v1/public/campaigns/{campaign_id}.
  3. Enroll a small test list or individual test lead with the same update call (add_lead_ids or add_lead_list_id).
  4. Get the campaign with include=preflight (GET /campaigns?id=...&include=preflight) and resolve every blocking issue.
  5. Launch only after confirming the campaign ID, audience, channel connections, and schedule, by setting status to running.
  6. Monitor campaign analytics and lead activity.

Enrollment

Send add_lead_ids or add_lead_list_id on the update call. The response carries enrollment with enrolled, skipped and total_requested. Remove leads with remove_lead_ids. Duplicate enrollment is a business result, not permission to retry blindly: leads already in the campaign are skipped. Inspect the response and the campaign’s leads (GET /leads?campaign_id=...) before resubmitting.

One call, several steps

An update can change settings, status and enrollment together. The steps run in a fixed order: settings and workflow, status, enrollment, removals. If a step fails, the steps before it stay applied and the error lists them under applied. Read the campaign before repeating the call.

Lifecycle safety

  • Preflight does not launch a campaign; it validates readiness.
  • status: running on a draft can create real outbound activity.
  • status: paused prevents future work but does not undo messages or calls already sent.
  • status: running on a paused campaign can restart future work.
  • status: stopped is a terminal or highly destructive transition; require explicit confirmation.
  • After a timeout, read the campaign state before repeating a transition.