Skip to content

Run a campaign

A campaign sends one message to many contacts. SMSFabric takes a snapshot of the audience, removes opted-out and blacklisted numbers, fills in each contact’s variables, and feeds the messages to your phones at a pace they can handle. Use it instead of a loop over POST /v1/messages whenever you have more than a handful of recipients.

You need:

  • Contacts, in groups or tagged. Create them with POST /v1/contacts or import a CSV with POST /v1/contact-imports (see the contact imports reference).
  • A key with campaigns:manage and messages:send (and contacts:manage to add contacts).
  • At least one online phone, unless you test with an sf_test_ key.
  1. Create a draft with POST /v1/campaigns.
  2. Check it with POST /v1/campaigns/:id/estimate: recipients, segments, duration and warnings.
  3. Start it with POST /v1/campaigns/:id/start.
  4. Follow progress with GET /v1/campaigns/:id or the campaign.completed webhook, then read GET /v1/campaigns/:id/report.

Give an inline body, or a templateId from POST /v1/templates. Either can use variables:

Variable Filled with
{{first_name}} The contact’s first name
{{last_name}} The contact’s last name
{{custom.<key>}} A custom field, such as {{custom.branch}}
{{first_name|there}} The first name, or there when it’s empty (fallback up to 60 characters)

A missing value without a fallback renders as nothing, and the double space it leaves is collapsed. Anything else in double braces is rejected with 400 template_invalid. Try a body against a real contact with POST /v1/templates/preview before you start.

Terminal window
# 1. Create the draft
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"],
"tags": ["vip"],
"body": "Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.",
"ratePerMinute": 60,
"quietHours": { "start": "21:00", "end": "09:00" }
}'
# 2. Estimate
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
# 3. Start
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

groupIds (up to 20) and tags (up to 20) are combined: a contact in any of the groups or with any of the tags is in the audience, once. At start, SMSFabric takes a snapshot and skips:

  • contacts who opted out (replied STOP, or marked optedOut),
  • numbers on the blacklist,
  • invalid numbers, and contacts whose rendered message is over 1,600 characters.

Starting with no recipients returns 422 campaign_audience_empty. Contacts added after the start are not included.

Setting Default Effect
ratePerMinute 120 Ceiling for the whole campaign, 1 to 6,000.
Phones Each phone also keeps the organization’s cooldown and jitter, SIM daily limits apply, and a pool fails over.
quietHours none { "start": "21:00", "end": "09:00" } in each recipient’s local time. May cross midnight.
timeZone Your organization’s time zone Used for numbers whose country is unknown.
scheduledAt now Start later, up to one year ahead. start then returns status: "scheduled".

A recipient’s local time comes from the contact’s timeZone, or the number’s country. For a country with several zones (US, CA, BR, RU, AU, MX…) the campaign waits until it is outside quiet hours in all of them.

Route the campaign with poolId, or deviceId and simId, but not both. Without them it uses normal routing (see Send messages).

The estimate tells you the real speed: effectiveRatePerMinute is the lower of ratePerMinute and what your phones can send. Watch its warnings:

Warning Meaning
empty_audience No one would receive it.
no_devices No phone can send on this route.
capacity_below_throttle Your phones are slower than ratePerMinute. Add phones to the pool, or expect a longer run.
unreachable_recipients At this pace, some recipients would not be reached within 14 days.
multi_zone_countries Some recipients are in countries with several time zones.
Call From To Effect
POST /v1/campaigns/:id/pause running paused No new recipient is claimed. Messages a phone already has still go out.
POST /v1/campaigns/:id/resume paused running Pacing restarts from now, without a burst.
POST /v1/campaigns/:id/cancel scheduled, running, paused canceled Final. Pending recipients are skipped; messages no phone has taken are blocked with errorCode: "campaign_canceled".

Any other transition returns 409 invalid_campaign_state. Only a draft can be edited (PATCH /v1/campaigns/:id) or deleted.

A campaign is completed when no recipient is pending and none of its messages is still queued, routed or sending.

GET /v1/campaigns/:id includes progress:

{
"recipients": 4812,
"pending": 3020,
"queued": 64,
"sent": 1690,
"delivered": 1544,
"failed": 12,
"skipped": 26,
"ratePerMinute": 58,
"etaAt": "2026-11-19T14:41:00.000Z"
}

Subscribe to campaign.started and campaign.completed to avoid polling. Each campaign message is an ordinary message with metadata.campaignId, so message.* webhooks and GET /v1/messages?campaignId=cmp_… work as usual.

When it ends, GET /v1/campaigns/:id/report returns skip reasons, failure codes, per-phone counts, the delivery rate and how far the run deviated from the estimate.

Start a campaign with an sf_test_ key and it runs in the sandbox: the campaign is marked sandbox: true, recipients are processed at your ratePerMinute, and every message goes sent then delivered without a phone. See Sandbox.