Contacts
sms.contacts is your address book: one contact per number, with tags, custom fields and consent. sms.contacts.groups and sms.contacts.imports manage static groups and CSV imports. sms.templates stores message bodies with {{variables}} for campaigns.
Contacts, groups and imports need contacts:read to read and contacts:manage to change. Templates need campaigns:read and campaigns:manage.
| Method | HTTP | Returns |
|---|---|---|
contacts.create(params, options?) |
POST /v1/contacts |
Contact |
contacts.list(params?) |
GET /v1/contacts |
Paginated<Contact> |
contacts.listAll(params?) |
GET /v1/contacts (every page) |
AsyncGenerator<Contact> |
contacts.get(id) |
GET /v1/contacts/:id |
Contact |
contacts.update(id, params) |
PATCH /v1/contacts/:id |
Contact |
contacts.delete(id) |
DELETE /v1/contacts/:id |
void |
contacts.tags(q?) |
GET /v1/contacts/tags |
Array<{ tag, contacts }> |
contacts.exportCsv(params?) |
GET /v1/contacts/export.csv |
string |
contacts.groups.create(params, options?) |
POST /v1/contact-groups |
ContactGroup |
contacts.groups.list(params?) |
GET /v1/contact-groups |
Paginated<ContactGroup> |
contacts.groups.listAll(params?) |
GET /v1/contact-groups (every page) |
AsyncGenerator<ContactGroup> |
contacts.groups.get(id) |
GET /v1/contact-groups/:id |
ContactGroup |
contacts.groups.update(id, params) |
PATCH /v1/contact-groups/:id |
ContactGroup |
contacts.groups.delete(id) |
DELETE /v1/contact-groups/:id |
void |
contacts.groups.addMembers(id, contactIds) |
POST /v1/contact-groups/:id/members |
{ changed, notFound, memberCount } |
contacts.groups.removeMembers(id, contactIds) |
POST /v1/contact-groups/:id/members/remove |
{ changed, notFound, memberCount } |
contacts.imports.upload(csv, fileName?) |
POST /v1/contact-imports |
ContactImport |
contacts.imports.start(id, params) |
POST /v1/contact-imports/:id/start |
ContactImport |
contacts.imports.get(id) |
GET /v1/contact-imports/:id |
ContactImport |
contacts.imports.list(params?) |
GET /v1/contact-imports |
Paginated<ContactImport> |
contacts.imports.listAll(params?) |
GET /v1/contact-imports (every page) |
AsyncGenerator<ContactImport> |
templates.create(params, options?) |
POST /v1/templates |
Template |
templates.list(params?) |
GET /v1/templates |
Paginated<Template> |
templates.listAll(params?) |
GET /v1/templates (every page) |
AsyncGenerator<Template> |
templates.get(id) |
GET /v1/templates/:id |
Template |
templates.update(id, params) |
PATCH /v1/templates/:id |
Template |
templates.delete(id) |
DELETE /v1/templates/:id |
void |
templates.preview(params) |
POST /v1/templates/preview |
TemplatePreview |
contacts.create
Section titled “contacts.create”Adds a contact. phone is E.164 and unique in your organization: a second contact with the same number returns 409 contact_exists.
| Parameter | Type | Notes |
|---|---|---|
phone |
string |
E.164. |
firstName, lastName, email |
string | null |
|
timeZone |
string | null |
IANA zone. Overrides the zone of the number’s country for quiet hours. |
tags |
string[] |
Up to 20, each 1 to 40 letters, digits, spaces, _ or -. |
customFields |
Record<string, string | number | boolean | null> |
snake_case keys, up to 50 keys and 4 KB, no nesting. |
consent |
{ source, at?, text? } |
Where the person agreed to receive messages: web_form, import, api, in_person, paper, sms_keyword or other. |
groupIds |
string[] |
Up to 20 groups to add the contact to. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const contact = await sms.contacts.create({ phone: '+201001234567', firstName: 'Mona', tags: ['vip', 'cairo'], customFields: { loyalty_tier: 'gold', visits: 12 }, consent: { source: 'web_form', text: 'I agree to receive appointment reminders by SMS.' }, groupIds: ['grp_…'],});console.log(contact.id, contact.country); // con_… EGcontacts.list
Section titled “contacts.list”One page of contacts, newest first. q matches a full number (exact), its last 4 digits, or a first name, last name or email (contains). Filter by tag, groupId or optedOut.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.contacts.list({ q: '4567', optedOut: false, limit: 10 });for (const c of page.data) console.log(c.id, c.phone, c.firstName);contacts.listAll
Section titled “contacts.listAll”Every matching contact, following cursors.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let count = 0;for await (const contact of sms.contacts.listAll({ tag: 'vip', limit: 200 })) { if (!contact.optedOut) count += 1;}console.log(`${count} reachable VIP contacts`);contacts.get
Section titled “contacts.get”One contact with its groups, consent and opt-out state.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const contact = await sms.contacts.get('con_…');console.log(contact.groups.map((g) => g.name), contact.optedOut?.source ?? 'subscribed');contacts.update
Section titled “contacts.update”Changes any field except groupIds. tags and customFields replace the stored values. optedOut: true marks the contact opted out; false clears it.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.update('con_…', { tags: ['vip'], timeZone: 'Africa/Cairo' });await sms.contacts.update('con_…', { optedOut: true }); // the person asked to stopcontacts.delete
Section titled “contacts.delete”Erases the contact with its tags and group memberships. Use it for an erasure request.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.delete('con_…');contacts.tags
Section titled “contacts.tags”Your tags, most used first (top 200), with the number of contacts on each. Pass a prefix to filter.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for (const { tag, contacts } of await sms.contacts.tags('ca')) console.log(tag, contacts);contacts.exportCsv
Section titled “contacts.exportCsv”Every contact, or those with a tag or in a groupId, as CSV text. Needs contacts:read and logs:export, and is recorded in the audit log.
import { writeFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await writeFile('vip.csv', await sms.contacts.exportCsv({ tag: 'vip' }));Groups
Section titled “Groups”Groups are static lists: members change only when you add or remove them, or when an import names the group.
groups.create
Section titled “groups.create”A group with a name (up to 120 characters, unique: 409 group_exists) and an optional description (up to 500).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const group = await sms.contacts.groups.create({ name: 'Newsletter', description: 'Monthly offers' });console.log(group.id, group.memberCount);groups.list
Section titled “groups.list”One page of groups (list) or all of them (listAll). q matches part of the name.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const g of sms.contacts.groups.listAll({ q: 'news' })) console.log(g.name, g.memberCount);groups.get, update, delete
Section titled “groups.get, update, delete”Read, rename or delete one group. Deleting a group keeps its contacts.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const group = await sms.contacts.groups.get('grp_…');await sms.contacts.groups.update(group.id, { name: 'Newsletter (EN)', description: null });await sms.contacts.groups.delete(group.id);groups.addMembers and removeMembers
Section titled “groups.addMembers and removeMembers”Add or remove up to 1,000 contacts per call. Ids that are not your contacts count as notFound and are never linked.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const added = await sms.contacts.groups.addMembers('grp_…', ['con_…', 'con_…']);console.log(added.changed, added.notFound, added.memberCount);
await sms.contacts.groups.removeMembers('grp_…', ['con_…']);Imports
Section titled “Imports”A CSV import has two steps: upload the file, then confirm how its columns map to contact fields. The rows are processed in the background, 500 at a time.
imports.upload
Section titled “imports.upload”Uploads a UTF-8 CSV (up to 5 MB and 100,000 rows; comma, semicolon or tab delimited) as a string or bytes. The result has the columns, a sample of the first 5 rows and a suggestedMapping guessed from English and Arabic headers.
import { readFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const upload = await sms.contacts.imports.upload(await readFile('customers.csv'), 'customers.csv');console.log(upload.id, upload.rowCount, upload.columns, upload.suggestedMapping);A file that does not parse returns 400 csv_<reason>; a file over 5 MB returns 413; another file type returns 415 unsupported_file_type.
imports.start
Section titled “imports.start”Confirms the mapping and starts the import. mapping.phone names the phone column; the other fields and custom (snake_case key → column) are optional. Set defaultCountry for national numbers such as 0100 123 4567, add every row to a groupId and tags, record consent, and choose whether to update contacts that already exist (updateExisting, default true).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const started = await sms.contacts.imports.start('imp_…', { mapping: { phone: 'Mobile', firstName: 'First name', email: 'Email', custom: { city: 'City' } }, defaultCountry: 'EG', groupId: 'grp_…', tags: ['import-nov'], consent: { source: 'import', text: 'Collected at checkout' },});console.log(started.status); // queuedimports.get and list
Section titled “imports.get and list”Poll get until status is completed or failed. The report counts skipped rows by reason (invalid_phone, duplicate_in_file, blacklisted…) and lists the first 500 with their line numbers.
import { setTimeout as sleep } from 'node:timers/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let job = await sms.contacts.imports.get('imp_…');while (job.status === 'queued' || job.status === 'processing') { await sleep(2_000); job = await sms.contacts.imports.get(job.id);}console.log(job.status, job.created, job.updated, job.skipped, job.report?.skipped);
const recent = await sms.contacts.imports.list({ limit: 5 });console.log(recent.data.map((i) => `${i.fileName}: ${i.status}`));Templates
Section titled “Templates”A template body may use {{first_name}}, {{last_name}} and {{custom.<key>}}, each with an optional fallback: {{first_name|there}}. Anything else between double braces returns 400 template_invalid.
templates.create
Section titled “templates.create”A name (up to 120 characters, unique) and a body (up to 1,600). The result includes the variables it uses and a segment preview for a sample contact.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const template = await sms.templates.create({ name: 'Appointment reminder', body: 'Hi {{first_name|there}}, see you tomorrow at {{custom.time}}. Reply STOP to opt out.',});console.log(template.variables, template.preview.segments, template.preview.encoding);templates.list
Section titled “templates.list”One page (list) or every template (listAll). q matches part of the name.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.templates.list({ q: 'reminder' });for (const t of page.data) console.log(t.id, t.name);templates.get, update, delete
Section titled “templates.get, update, delete”Read, change or delete one template. Campaigns keep their own copy of the text, so changing or deleting a template does not change a campaign that used it.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const template = await sms.templates.get('tpl_…');await sms.templates.update(template.id, { body: `${template.body} See you soon.` });await sms.templates.delete(template.id);templates.preview
Section titled “templates.preview”Renders a body for one of your contacts, or a sample contact, without saving anything. Template problems come back in issues rather than as an error, so you can show them while the user types.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const preview = await sms.templates.preview({ body: 'Hi {{first_name}}, your code is {{custom.code}}', contactId: 'con_…' });console.log(preview.rendered);console.log(preview.segments); // { encoding: 'GSM7', segments: 1, characters: 31 }for (const issue of preview.issues) console.log(issue.code, issue.token);