Messages
sms.messages sends SMS through your gateway phones and reads what was sent and received. Sending needs the messages:send scope, reading needs messages:read, and the CSV export needs logs:export.
| Method | HTTP | Returns |
|---|---|---|
send(params, options?) |
POST /v1/messages |
Message[] |
list(params?) |
GET /v1/messages |
Paginated<Message> |
listAll(params?) |
GET /v1/messages (every page) |
AsyncGenerator<Message> |
get(id) |
GET /v1/messages/:id |
MessageWithEvents |
stats(params?) |
GET /v1/messages/stats |
MessageStats |
exportCsv(params?) |
GET /v1/messages/export.csv |
string |
Sends one body to one recipient or up to 100. It returns one Message per recipient, in the same order, with status queued, or blocked for a number on your blacklist.
| Parameter | Type | Notes |
|---|---|---|
to |
string | string[] |
E.164 numbers, up to 100. |
body |
string |
Up to 1,600 characters. Long texts go out as several segments. |
deviceId |
string |
Send from this phone. |
simId |
string |
Send from this SIM. |
poolId |
string |
Round-robin over the pool’s online phones, with failover. |
scheduledAt |
Date | string |
Send later. |
metadata |
Record<string, unknown> |
Your own data, returned on the message and in its webhooks. |
With no route, the message goes through the organization’s default SIM. The second argument takes an idempotencyKey; see Idempotency.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const messages = await sms.messages.send( { to: ['+201001234567', '+201001234568'], body: 'The clinic is closed on Friday. Reply STOP to opt out.', poolId: 'pool_…', metadata: { notice: 'friday-closure' }, }, { idempotencyKey: 'friday-closure-2026-11-20' },);
for (const m of messages) console.log(m.id, m.to, m.status, m.segments);One page of messages, newest first. Filter by direction (outbound, inbound), status, deviceId, campaignId, q (a phone number), and a from / to date range. limit is 1 to 200 (default 50); pass the returned nextCursor as cursor for the next page.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.messages.list({ status: 'failed', from: new Date(Date.now() - 24 * 60 * 60 * 1000), limit: 100,});
for (const m of page.data) console.log(m.createdAt, m.to, m.errorCode);if (page.nextCursor) console.log('More with cursor', page.nextCursor);listAll
Section titled “listAll”The same filters as list, without cursor. It follows every cursor and yields one message at a time, so you can stop early with break.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const midnight = new Date();midnight.setUTCHours(0, 0, 0, 0);
for await (const m of sms.messages.listAll({ direction: 'inbound', from: midnight })) { console.log(m.from, m.body);}One message with its delivery timeline in events: queued, routed, sending, sent, delivered or failed, with the phone that handled each step.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const message = await sms.messages.get('msg_…');console.log(message.status, message.deliveredAt);for (const e of message.events) console.log(e.createdAt, e.type, e.status);Verification codes sent by Verify are messages too, but their body always reads [verification code hidden].
Daily sent, delivered and failed counts for the last days UTC days (1 to 31, default 7), ending today, plus totals.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const stats = await sms.messages.stats({ days: 14 });for (const day of stats.days) console.log(day.date, day.sent, day.delivered, day.failed);console.log('Queued now:', stats.totals.queued);exportCsv
Section titled “exportCsv”The same filters as list (without limit and cursor), returned as CSV text. Cells are escaped so a spreadsheet never runs one as a formula. Needs logs:export.
import { writeFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const csv = await sms.messages.exportCsv({ campaignId: 'cmp_…' });await writeFile('campaign-messages.csv', csv);The export holds phone numbers and message text. Store the file as carefully as the data in the portal.