Account
These resources cover the organization the credentials belong to. Some of them refuse API keys, so that a leaked key cannot change who has access: they need a signed-in user’s access token (why). The Auth column says which.
| Method | HTTP | Returns | Auth |
|---|---|---|---|
org.get() |
GET /v1/org |
Org |
API key or user |
org.update(params) |
PATCH /v1/org |
Org |
User, settings:manage |
org.plan() |
GET /v1/org/plan |
OrgPlan |
API key or user |
org.members.list() |
GET /v1/org/members |
Member[] |
User |
org.members.update(userId, params) |
PATCH /v1/org/members/:userId |
Member |
User, members:manage |
org.members.remove(userId) |
DELETE /v1/org/members/:userId |
void |
User, members:manage |
org.invitations.list() |
GET /v1/org/invitations |
Invitation[] |
User, members:manage |
org.invitations.create(params, options?) |
POST /v1/org/invitations |
Invitation |
User, members:manage |
org.invitations.revoke(id) |
DELETE /v1/org/invitations/:id |
void |
User, members:manage |
preferences.get() |
GET /v1/preferences |
Preferences |
API key or user |
preferences.update(params) |
PATCH /v1/preferences |
Preferences |
settings:manage |
audit.list(params?) |
GET /v1/audit |
Paginated<AuditEntry> |
audit:read |
audit.listAll(params?) |
GET /v1/audit (every page) |
AsyncGenerator<AuditEntry> |
audit:read |
blacklist.list(params?) |
GET /v1/blacklist |
Paginated<BlacklistEntry> |
blacklist:manage |
blacklist.listAll(params?) |
GET /v1/blacklist (every page) |
AsyncGenerator<BlacklistEntry> |
blacklist:manage |
blacklist.add(params, options?) |
POST /v1/blacklist |
BlacklistEntry |
blacklist:manage |
blacklist.remove(id) |
DELETE /v1/blacklist/:id |
void |
blacklist:manage |
Organization
Section titled “Organization”org.get
Section titled “org.get”The organization’s id, name, slug, status and plan. Works with any API key, which makes it a cheap check that a key is valid.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const org = await sms.org.get();console.log(org.id, org.name, org.plan);org.plan
Section titled “org.plan”The plan, its limits with add-ons applied, which limits staff overrode for you, and the usage counted against them. When the allowance runs out, sends fail with 429 quota_exceeded; the SDK does not retry those, and error.params carries the plan, the limit and when it resets.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const { plan, limits, usage } = await sms.org.plan();console.log(plan.name, usage.messagesThisMonth, limits.messagesPerMonth ?? 'no limit');org.update
Section titled “org.update”Renames the organization.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.org.update({ name: 'Acme Clinics' });Members
Section titled “Members”org.members.list
Section titled “org.members.list”Everyone in the organization with their role (owner, admin, developer, campaign_manager, agent, viewer, billing).
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
for (const m of await admin.org.members.list()) console.log(m.userId, m.email, m.role);org.members.update
Section titled “org.members.update”Changes a member’s role. The change is recorded in the audit log.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.org.members.update('usr_…', { role: 'campaign_manager' });org.members.remove
Section titled “org.members.remove”Removes a member from the organization. Their account stays; they lose access to this organization.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.org.members.remove('usr_…');Invitations
Section titled “Invitations”org.invitations.list
Section titled “org.invitations.list”Invitations with their email, role, expiresAt and acceptedAt.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const open = (await admin.org.invitations.list()).filter((i) => !i.acceptedAt);console.log(open.map((i) => `${i.email} (${i.role})`));org.invitations.create
Section titled “org.invitations.create”Emails an invitation to join with a role.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const invitation = await admin.org.invitations.create({ email: 'sara@acme.example', role: 'developer' });console.log(invitation.id, invitation.expiresAt);org.invitations.revoke
Section titled “org.invitations.revoke”Cancels an invitation that has not been accepted yet.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.org.invitations.revoke('inv_…');Preferences
Section titled “Preferences”preferences.get
Section titled “preferences.get”The organization’s sending preferences: cooldownMs and jitterMs between two messages from one phone, maxRetries, the default phone and SIM, the sendWindow, inbound forwarding and the timeZone used for campaign quiet hours.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const prefs = await sms.preferences.get();console.log(prefs.cooldownMs, prefs.jitterMs, prefs.defaultSimId, prefs.timeZone);preferences.update
Section titled “preferences.update”Changes any of them. cooldownMs and jitterMs are 0 to 600,000 ms, maxRetries 0 to 10, sendWindow is { start: 'HH:mm', end: 'HH:mm', tz } or null, and forwardInbound is { email?, phone?, webhook? } or null.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.preferences.update({ cooldownMs: 5_000, jitterMs: 3_000, sendWindow: { start: '09:00', end: '21:00', tz: 'Africa/Cairo' }, timeZone: 'Africa/Cairo',});Audit log
Section titled “Audit log”audit.list and listAll
Section titled “audit.list and listAll”Security events and changes, newest first: sign-ins, key creation, role changes, campaign starts, exports and more. Filter by an exact action, such as apikey.created, or with q by part of the action or the actor’s name or email. Each entry’s actor has the name to show (null for SMSFabric staff and the system).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const entry of sms.audit.listAll({ action: 'campaign.started' })) { console.log(entry.createdAt, entry.actor.name ?? entry.actor.type, entry.action, entry.targetId);}Blacklist
Section titled “Blacklist”Numbers on the blacklist never receive messages: a send to one comes back with status: 'blocked'. A recipient who replies STOP is added with source: 'opt_out', and START removes that entry again.
blacklist.list and listAll
Section titled “blacklist.list and listAll”import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const entry of sms.blacklist.listAll()) console.log(entry.phone, entry.source, entry.reason);blacklist.add
Section titled “blacklist.add”Adds an E.164 number, with an optional reason (up to 500 characters).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const entry = await sms.blacklist.add({ phone: '+201001234567', reason: 'Asked by phone not to be contacted' });console.log(entry.id);blacklist.remove
Section titled “blacklist.remove”Removes an entry by its id. Only remove an opt_out entry when the person has asked to receive messages again.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.blacklist.remove('blk_…');