Campaigns
sms.campaigns sends one body or template to the contacts in some groups and/or with some tags. Each contact gets it once; opted-out and blacklisted numbers are left out. Reading needs campaigns:read, changes need campaigns:manage, and starting also needs messages:send. The concepts are in Campaigns.
A campaign moves through draft → scheduled → running ⇄ paused → completed, and can be canceled from scheduled, running or paused.
| Method | HTTP | Returns |
|---|---|---|
create(params, options?) |
POST /v1/campaigns |
Campaign |
list(params?) |
GET /v1/campaigns |
Paginated<Campaign> |
listAll(params?) |
GET /v1/campaigns (every page) |
AsyncGenerator<Campaign> |
get(id) |
GET /v1/campaigns/:id |
Campaign |
update(id, params) |
PATCH /v1/campaigns/:id |
Campaign |
delete(id) |
DELETE /v1/campaigns/:id |
void |
estimate(id) |
POST /v1/campaigns/:id/estimate |
CampaignEstimate |
start(id) |
POST /v1/campaigns/:id/start |
Campaign |
pause(id) |
POST /v1/campaigns/:id/pause |
Campaign |
resume(id) |
POST /v1/campaigns/:id/resume |
Campaign |
cancel(id) |
POST /v1/campaigns/:id/cancel |
Campaign |
report(id) |
GET /v1/campaigns/:id/report |
CampaignReport |
create
Section titled “create”Creates a draft. Nothing is sent until you call start.
| Parameter | Type | Notes |
|---|---|---|
name |
string |
Required. |
groupIds |
string[] |
Up to 20 groups. |
tags |
string[] |
Up to 20 tags. A contact matches if it is in any group or has any tag. |
templateId or body |
string |
One of them. A body may use {{first_name}}, {{last_name}} and {{custom.<key>}}. |
poolId, or deviceId and simId |
string |
The route. Not both. Default: the organization’s default SIM. |
ratePerMinute |
number |
1 to 6,000 messages per minute across the campaign. Default 120. |
hourlyCap |
number | null |
Most recipients per clock hour in timeZone (1 to 360,000). |
dailyCap |
number | null |
Most recipients per calendar day in timeZone (1 to 8,640,000), not below hourlyCap. |
quietHours |
{ start, end } | null |
HH:MM in each recipient’s local time; may cross midnight, e.g. 21:00 to 09:00. |
timeZone |
string |
IANA zone for numbers without a country. Default: your preferences’ timeZone. |
scheduledAt |
Date | string | null |
Start later (up to a year ahead) instead of at once. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const campaign = await sms.campaigns.create({ name: 'November offers', groupIds: ['grp_…'], tags: ['vip'], body: 'Hi {{first_name|there}}, 20% off this weekend. Reply STOP to opt out.', poolId: 'pool_…', ratePerMinute: 60, quietHours: { start: '21:00', end: '09:00' },});console.log(campaign.id, campaign.status); // cmp_… draftInclude opt-out wording. A recipient who replies STOP is added to your blacklist and skipped by every later campaign.
list and listAll
Section titled “list and listAll”Campaigns, newest first, each with live progress. Filter by status.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const c of sms.campaigns.listAll({ status: 'running' })) { console.log(c.name, `${c.progress.sent}/${c.progress.recipients}`, 'ETA', c.progress.etaAt);}One campaign. progress has recipients, pending, queued, sent, delivered, failed, skipped, the measured ratePerMinute (last 30 seconds) and etaAt.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const c = await sms.campaigns.get('cmp_…');console.log(c.status, c.progress);update
Section titled “update”Changes any create field. Drafts only: any other state returns 409 invalid_campaign_state.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.update('cmp_…', { ratePerMinute: 30, scheduledAt: new Date('2026-11-21T08:00:00Z') });delete
Section titled “delete”Deletes a draft. A campaign that has started can be canceled instead.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.delete('cmp_…');estimate
Section titled “estimate”What the campaign will do before you start it: recipients after opt-outs and the blacklist, total segments, phone capacity, the effective rate, how many recipients wait for quiet hours, the expected duration and warnings (empty_audience, no_devices, capacity_below_throttle, unreachable_recipients, multi_zone_countries). Works on drafts and scheduled campaigns.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const e = await sms.campaigns.estimate('cmp_…');console.log(`${e.recipients} recipients, ${e.segments} segments, ${e.effectiveRatePerMinute}/min`);console.log('Excluded:', e.excluded, 'Done by', e.completesAt ?? 'never (see warnings)');if (e.warnings.length) console.warn(e.warnings);Starts a draft now, or schedules it when scheduledAt is in the future. With an sf_test_ key the campaign runs in the sandbox. An empty audience returns 422 campaign_audience_empty.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const estimate = await sms.campaigns.estimate('cmp_…');if (estimate.warnings.length === 0 && estimate.recipients <= 5_000) { const c = await sms.campaigns.start('cmp_…'); console.log(c.status); // running or scheduled}pause and resume
Section titled “pause and resume”pause stops claiming new recipients; messages a phone already has still go out. resume continues, and the throttle restarts from that moment, so there is no burst.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.pause('cmp_…');// …fix the problem…await sms.campaigns.resume('cmp_…');cancel
Section titled “cancel”Ends a scheduled, running or paused campaign for good. Pending recipients are skipped with reason canceled, and messages no phone has taken yet are blocked with errorCode: 'campaign_canceled'. It cannot be undone.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const c = await sms.campaigns.cancel('cmp_…');console.log(c.status, c.progress.skipped); // canceled …report
Section titled “report”The final picture: skips by reason (blacklisted, opted_out, canceled, contact_deleted, invalid_number, body_too_long), failures by error code, counts per phone and SIM, the actual duration, how far it was from the estimate and the delivery rate.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const r = await sms.campaigns.report('cmp_…');console.log('Delivery rate', r.deliveryRate, 'skipped', r.skipped, 'failures', r.failures);for (const row of r.byDevice) console.log(row.deviceName, row.sent, row.delivered, row.failed);Every message a campaign sends is an ordinary message with metadata.campaignId, so sms.messages.list({ campaignId }) lists them.