Node SDK
@smsfabric/sdk is the official Node.js client for the SMSFabric API. It wraps every customer endpoint in a typed method, retries the requests that are safe to retry, and verifies webhook signatures in one call.
- Typed requests and responses, written against the API reference.
- ESM and CommonJS builds with type declarations. No runtime dependencies.
- Retries
429,5xxand network errors with backoff that honoursRetry-After. - Every create sends an
Idempotency-Key, so an automatic retry never sends twice. - Node.js 20 or newer. It uses the built-in
fetch,FormDataandnode:crypto.
Install
Section titled “Install”npm install @smsfabric/sdkpnpm add @smsfabric/sdkyarn add @smsfabric/sdkSend your first message
Section titled “Send your first message”Create an API key with the messages:send scope under Developers → API keys in the portal (walkthrough). Start with a test key (sf_test_…): its messages go to the built-in virtual device and never reach a real phone. Put it in the environment:
export SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThen send:
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const [message] = await sms.messages.send({ to: '+201001234567', body: 'Your order 1042 has shipped.',});
console.log(message?.id, message?.status); // msg_… queuedsend returns one Message per recipient, with status queued (or blocked for a blacklisted number). Delivery continues in the background: read it with sms.messages.get(id) or receive it as a message.delivered webhook.
What the client covers
Section titled “What the client covers”Each property of the client is one resource. Every paginated list also has a listAll async iterator that follows the cursors for you.
| Property | What it covers | Page |
|---|---|---|
messages |
Send, list, get, daily stats, CSV export | Messages |
verifications |
One-time codes: send, check, get, list; settings for SMS-pumping protection |
Verifications |
devices |
Pairing tokens, gateway phones and their SIMs | Devices |
pools |
High-availability groups of phones | Devices |
contacts |
Contacts, groups and CSV imports |
Contacts |
templates |
Message templates with {{variables}} and previews |
Contacts |
campaigns |
Bulk sends: estimate, start, pause, resume, cancel, report | Campaigns |
webhooks |
Endpoints, deliveries, replay, test events, signature verification | Webhooks |
apiKeys |
Create, rotate and revoke API keys | API keys |
org |
Organization profile, members and invitations |
Account |
preferences |
Cooldown, jitter, default SIM, send window, time zone | Account |
audit |
The organization’s audit log | Account |
blacklist |
Numbers that never receive messages | Account |
http |
The low-level client, for an endpoint without a helper | Configuration |