Skip to content

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.

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

list-failed.ts
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);

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.

inbound-today.ts
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.

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

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

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.

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