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.
Before you start
Section titled “Before you start”You need:
- Contacts, in groups or tagged. Create them with
POST /v1/contactsor import a CSV withPOST /v1/contact-imports(see the contact imports reference). - A key with
campaigns:manageandmessages:send(andcontacts:manageto add contacts). - At least one online phone, unless you test with an
sf_test_key.
- Create a draft with
POST /v1/campaigns. - Check it with
POST /v1/campaigns/:id/estimate: recipients, segments, duration and warnings. - Start it with
POST /v1/campaigns/:id/start. - Follow
progresswithGET /v1/campaigns/:idor thecampaign.completedwebhook, then readGET /v1/campaigns/:id/report.
Write the message
Section titled “Write the message”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.
Create, estimate and start
Section titled “Create, estimate and start”# 1. Create the draftcurl 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. Estimatecurl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \ -H "X-Api-Key: $SMSFABRIC_API_KEY"
# 3. Startcurl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const draft = await sf.campaigns.create( { 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' }, }, { idempotencyKey: 'winter-sale-2026' },);
const estimate = await sf.campaigns.estimate(draft.id);console.log(estimate.recipients, 'recipients,', estimate.warnings);
if (!estimate.warnings.includes('no_devices')) { const running = await sf.campaigns.start(draft.id); console.log(running.status); // running, or scheduled}import osimport requests
API = "https://api.smsfabric.com"headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}
draft = requests.post( f"{API}/v1/campaigns", headers={**headers, "Idempotency-Key": "winter-sale-2026"}, json={ "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"}, }, timeout=30,).json()
estimate = requests.post(f"{API}/v1/campaigns/{draft['id']}/estimate", headers=headers, timeout=30).json()print(estimate["recipients"], estimate["warnings"])
started = requests.post(f"{API}/v1/campaigns/{draft['id']}/start", headers=headers, timeout=30)started.raise_for_status()print(started.json()["status"])<?phpfunction sf(string $method, string $path, ?array $body = null, array $extra = []): array { $ch = curl_init('https://api.smsfabric.com' . $path); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => $method, CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body), CURLOPT_HTTPHEADER => array_merge(['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json'], $extra), CURLOPT_RETURNTRANSFER => true, ]); return json_decode(curl_exec($ch), true);}
$draft = sf('POST', '/v1/campaigns', [ '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'],], ['Idempotency-Key: winter-sale-2026']);
$estimate = sf('POST', "/v1/campaigns/{$draft['id']}/estimate");echo $estimate['recipients'] . " recipients\n";
$started = sf('POST', "/v1/campaigns/{$draft['id']}/start");echo $started['status'] . "\n";Audience
Section titled “Audience”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.
Pacing and quiet hours
Section titled “Pacing and quiet hours”| 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. |
Control a running campaign
Section titled “Control a running campaign”| 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.
Follow progress
Section titled “Follow progress”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.
Test in the sandbox
Section titled “Test in the sandbox”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.