Campaigns

A campaign sends one message to an audience. You create a draft, look at the estimate, then start it now or schedule it.

1. Create a draft#

POST /v1/campaigns (needs campaigns:write) takes the text or a template_id, and the audience from any mix of group_ids, smart_list_ids, the import_id of a contacts CSV import, and up to 10,000 addresses. Defaults are category: marketing, opt-out text appended to marketing, link shortening and click tracking on. Assert consent with compliance.consent_asserted: true; MyComm stamps the assertion with the caller and keeps it.

Problems that would stop the campaign are reported at once, each with its own code (AUDIENCE_EMPTY, BODY_EMPTY, TEMPLATE_INVALID, LINK_BLOCKED, CONTENT_PROHIBITED, CATEGORY_MISMATCH, CHANNEL_INACTIVE, ...).

2. Estimate#

POST /v1/campaigns/{id}/estimate expands the audience without saving anything and returns the figures to review: recipients, the ones skipped (opted out, over the frequency cap, no identity for the channel), segments, and when sending would start and finish given quiet hours and the SIM's pace. It is limited to 10 a minute per key and campaign. Exact figures come when the campaign starts and the audience is expanded.

3. Start or schedule#

POST /v1/campaigns/{id}/start runs a draft now, or schedules it when scheduled_at is in the future. The start checks run again and can refuse with CONSENT_ASSERTION_REQUIRED, CONSENT_PROVENANCE_MISSING, MARKETING_NOT_ALLOWED, ACCOUNT_THROTTLED or NEW_ACCOUNT_LIMIT among others. POST /v1/campaigns/{id}/unschedule takes a scheduled campaign back to a draft.

Quiet hours and frequency caps are applied again at send time, not only in the estimate.

4. Pause, resume, cancel#

pause holds the campaign's unsent messages (hold_reason: campaign_paused); messages already on a phone finish. resume releases them without duplicating anyone: each recipient is sent at most once. cancel ends the campaign: pending recipients and queued campaign messages become cancelled. Any other state answers 409 INVALID_STATE.

5. Follow it#

• GET /v1/campaigns/{id} has the status and counts; GET /v1/campaigns/{id}/recipients has one row per recipient.
• GET /v1/campaigns/{id}/report has delivery, failure and click figures.
• Events: campaign.scheduled, campaign.unscheduled, campaign.started, campaign.paused, campaign.resumed, campaign.completed and campaign.cancelled. See the event catalogue.

A campaign goes through the same safety rules as any message, so a large audience takes the time the SIM's pace requires. The estimate tells you how long.