Skip to content

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.

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
GET/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.
Terminal window
curl "https://api.smsfabric.com/v1/campaigns?status=running" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/campaignscampaigns:manage

Creates 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.
Terminal window
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.
GET/v1/campaigns/:idcampaigns:read
Terminal window
curl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

Returns the campaign with live progress.

PATCH/v1/campaigns/:idcampaigns:manage

Drafts only. Takes any create field. Returns the campaign. 409 invalid_campaign_state for any other status.

Terminal window
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/v1/campaigns/:idcampaigns:manage

Drafts only. Returns 204.

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/campaigns/:id/estimatecampaigns:read

For 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.

Terminal window
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.

POST/v1/campaigns/:id/startcampaigns:manage, messages:send

Takes 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.

Terminal window
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.
POST/v1/campaigns/:id/pausecampaigns:manage

running → paused. No new recipient is claimed; messages a phone already has still go out. Returns the campaign. Audited as campaign.paused.

Terminal window
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/pause \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/campaigns/:id/resumecampaigns:manage

paused → running. Pacing restarts from now, without a burst. Returns the campaign. Audited as campaign.resumed.

Terminal window
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/resume \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/campaigns/:id/cancelcampaigns:manage

scheduled, 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".

Terminal window
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/cancel \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
GET/v1/campaigns/:id/reportcampaigns:read
Terminal window
curl 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.