Skip to content

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

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.
create-campaign.ts
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_… draft

Include opt-out wording. A recipient who replies STOP is added to your blacklist and skipped by every later campaign.

Campaigns, newest first, each with live progress. Filter by status.

running-campaigns.ts
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.

get-campaign.ts
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);

Changes any create field. Drafts only: any other state returns 409 invalid_campaign_state.

update-campaign.ts
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') });

Deletes a draft. A campaign that has started can be canceled instead.

delete-campaign.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.delete('cmp_…');

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.

estimate.ts
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.

start.ts
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 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.

pause-resume.ts
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_…');

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.

cancel.ts
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 …

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.

report.ts
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.