Campaigns
A campaign sends one message to every contact in some groups and/or with some tags, each contact once, minus opted-out and blacklisted numbers. See Run a campaign for the walkthrough.
States: draft → scheduled → running ⇄ paused → completed, and canceled from scheduled, running or paused. completed and canceled are final. Any other transition returns 409 invalid_campaign_state.
The campaign object
Section titled “The campaign object”| Field | Type | Description |
|---|---|---|
id |
string | cmp_… |
name |
string | |
status |
string | draft, scheduled, running, paused, completed or canceled. |
templateId |
string or null | The template the body came from. |
body |
string | The campaign’s own copy of the text. |
variables |
string[] | Variables in the body. |
audience |
object | { groupIds, tags }. |
route |
object | { poolId, deviceId, simId }. |
ratePerMinute |
integer | Pacing ceiling. |
hourlyCap, dailyCap |
integer or null | Most recipients per clock hour and per calendar day in timeZone; null for no cap. |
quietHours |
object or null | { start, end } in HH:MM, recipients’ local time. |
timeZone |
string | Fallback zone for numbers without a country. |
sandbox |
boolean | true when started with an sf_test_ key. |
scheduledAt, startedAt, pausedAt, completedAt, canceledAt |
string or null | |
estimatedDurationMs |
integer or null | Estimate at start. |
segments |
integer | Segments of the body rendered for a sample contact. |
progress |
object | { recipients, pending, queued, sent, delivered, failed, skipped, ratePerMinute, etaAt, capped, cappedUntil }. sent includes delivered; ratePerMinute is measured over the last 30 seconds. capped is hourly or daily while a cap holds the campaign (it stays running), and cappedUntil says when the window opens. |
createdAt, updatedAt |
string |
List campaigns
Section titled “List campaigns”/v1/campaignscampaigns:read| Query | Type | Description |
|---|---|---|
status |
string | One campaign status. |
limit |
integer | 1 to 200, default 50. |
cursor |
string | nextCursor from the previous page. |
curl "https://api.smsfabric.com/v1/campaigns?status=running" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Create a campaign
Section titled “Create a campaign”/v1/campaignscampaigns:manageCreates a draft. Returns 201. Supports Idempotency-Key.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
name |
string | Yes | 1 to 120 characters. | |
groupIds |
string[] | No | Audience groups. | Up to 20. |
tags |
string[] | No | Audience tags. | Up to 20. |
templateId |
string | One of | Use this template’s body. | Give templateId or body, not both. |
body |
string | One of | Inline text with variables. | 1 to 1,600 characters. |
poolId |
string | No | Route through this pool. | Not with deviceId/simId. |
deviceId, simId |
string | No | Route through this phone or SIM. | The SIM must be in the phone. |
ratePerMinute |
integer | No | Pacing ceiling. | 1 to 6,000, default 120. |
hourlyCap |
integer or null | No | Most recipients per clock hour in timeZone. |
1 to 360,000. |
dailyCap |
integer or null | No | Most recipients per calendar day in timeZone. |
1 to 8,640,000, not below hourlyCap. |
quietHours |
object or null | No | { "start": "21:00", "end": "09:00" }. |
HH:MM, 24-hour; may cross midnight. |
timeZone |
string | No | Fallback IANA zone. | Default: your organization’s timeZone preference. |
scheduledAt |
string | No | Start time used by start. |
Future, at most one year ahead. |
curl https://api.smsfabric.com/v1/campaigns \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: winter-sale-2026" \ -d '{ "name": "Winter sale", "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"], "templateId": "tpl_h7k0n3q6t9w2z5c8f1i4l7o0", "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9", "ratePerMinute": 60, "quietHours": { "start": "21:00", "end": "09:00" } }'{ "id": "cmp_e1h4k7n0q3t6w9z2c5f8i1l4", "name": "Winter sale", "status": "draft", "templateId": "tpl_h7k0n3q6t9w2z5c8f1i4l7o0", "body": "Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.", "variables": ["first_name", "custom.branch"], "audience": { "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"], "tags": [] }, "route": { "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9", "deviceId": null, "simId": null }, "ratePerMinute": 60, "quietHours": { "start": "21:00", "end": "09:00" }, "timeZone": "Africa/Cairo", "sandbox": false, "scheduledAt": null, "startedAt": null, "pausedAt": null, "completedAt": null, "canceledAt": null, "estimatedDurationMs": null, "segments": 1, "progress": { "recipients": 0, "pending": 0, "queued": 0, "sent": 0, "delivered": 0, "failed": 0, "skipped": 0, "ratePerMinute": 0, "etaAt": null }, "createdAt": "2026-11-19T12:00:00.000Z", "updatedAt": "2026-11-19T12:00:00.000Z"}| Error | When |
|---|---|
400 validation_failed |
Neither or both of body and templateId, both poolId and deviceId/simId, a SIM not in the device, or a past scheduledAt. |
400 template_invalid |
The body has invalid variables. |
404 not_found |
A group, template, pool, device or SIM is not in your organization. |
Retrieve a campaign
Section titled “Retrieve a campaign”/v1/campaigns/:idcampaigns:readcurl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Returns the campaign with live progress.
Update a campaign
Section titled “Update a campaign”/v1/campaigns/:idcampaigns:manageDrafts only. Takes any create field. Returns the campaign. 409 invalid_campaign_state for any other status.
curl -X PATCH https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scheduledAt": "2026-11-21T08:00:00Z"}'Delete a campaign
Section titled “Delete a campaign”/v1/campaigns/:idcampaigns:manageDrafts only. Returns 204.
curl -X DELETE https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Estimate a campaign
Section titled “Estimate a campaign”/v1/campaigns/:id/estimatecampaigns:readFor drafts and scheduled campaigns: recipients, segments and duration given the throttle, your phones’ capacity and quiet hours. Returns 200. Counts toward the bulk rate limit.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "recipients": 4812, "excluded": { "blacklisted": 14, "optedOut": 37 }, "segments": 4890, "ucs2Recipients": 0, "devices": 3, "capacityPerMinute": 42, "effectiveRatePerMinute": 42, "waitingForQuietHours": 0, "multiZoneRecipients": 0, "unreachable": 0, "capDays": null, "durationMs": 6874000, "startsAt": "2026-11-19T12:05:00.000Z", "completesAt": "2026-11-19T13:59:34.000Z", "zones": [{ "zone": "Africa/Cairo", "recipients": 4812, "quietNow": false, "opensAt": null }], "warnings": ["capacity_below_throttle"]}segments is the total over all recipients, each message rendered with that contact’s variables. Warnings: empty_audience, no_devices, capacity_below_throttle, unreachable_recipients, multi_zone_countries. See Pacing and quiet hours.
Start a campaign
Section titled “Start a campaign”/v1/campaigns/:id/startcampaigns:manage, messages:sendTakes the audience snapshot and moves a draft to running, or to scheduled when scheduledAt is in the future. With an sf_test_ key the campaign runs in the sandbox. Returns 200 with the campaign. Counts toward the bulk rate limit. Audited as campaign.started; sends the campaign.started webhook.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \ -H "X-Api-Key: $SMSFABRIC_API_KEY"| Error | When |
|---|---|
422 campaign_audience_empty |
No contact is left after exclusions. |
409 invalid_campaign_state |
The campaign is not a draft. |
Pause a campaign
Section titled “Pause a campaign”/v1/campaigns/:id/pausecampaigns:managerunning → paused. No new recipient is claimed; messages a phone already has still go out. Returns the campaign. Audited as campaign.paused.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/pause \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Resume a campaign
Section titled “Resume a campaign”/v1/campaigns/:id/resumecampaigns:managepaused → running. Pacing restarts from now, without a burst. Returns the campaign. Audited as campaign.resumed.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/resume \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Cancel a campaign
Section titled “Cancel a campaign”/v1/campaigns/:id/cancelcampaigns:managescheduled, running or paused → canceled (final). Pending recipients are skipped with canceled; messages no phone has taken are blocked with errorCode: "campaign_canceled". Returns the campaign. Audited as campaign.canceled; sends campaign.completed with status: "canceled".
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/cancel \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Get a campaign report
Section titled “Get a campaign report”/v1/campaigns/:id/reportcampaigns:readcurl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/report \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "campaign": { "id": "cmp_e1h4k7n0q3t6w9z2c5f8i1l4", "name": "Winter sale", "status": "completed" }, "skipped": { "blacklisted": 14, "opted_out": 37, "invalid_number": 3 }, "failures": { "no_service": 9, "generic_failure": 2 }, "byDevice": [ { "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "deviceName": "Pixel 8 · front desk", "simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "queued": 0, "sent": 1598, "delivered": 1561, "failed": 5 } ], "durationMs": 7012000, "estimateDeviation": 0.02, "deliveryRate": 0.97}(campaign is shortened here; it is the full campaign object.) Skip reasons: blacklisted, opted_out, canceled, contact_deleted, invalid_number, body_too_long (the body rendered for that contact is over 1,600 characters). failures counts message errorCodes.