Skip to content

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

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.
create-contact.ts
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_… EG

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.

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

Every matching contact, following cursors.

vip-count.ts
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`);

One contact with its groups, consent and opt-out state.

get-contact.ts
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');

Changes any field except groupIds. tags and customFields replace the stored values. optedOut: true marks the contact opted out; false clears it.

update-contact.ts
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 stop

Erases the contact with its tags and group memberships. Use it for an erasure request.

delete-contact.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.delete('con_…');

Your tags, most used first (top 200), with the number of contacts on each. Pass a prefix to filter.

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

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.

export-contacts.ts
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 are static lists: members change only when you add or remove them, or when an import names the group.

A group with a name (up to 120 characters, unique: 409 group_exists) and an optional description (up to 500).

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

One page of groups (list) or all of them (listAll). q matches part of the name.

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

Read, rename or delete one group. Deleting a group keeps its contacts.

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

Add or remove up to 1,000 contacts per call. Ids that are not your contacts count as notFound and are never linked.

group-members.ts
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_…']);

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.

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.

upload-import.ts
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.

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).

start-import.ts
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); // queued

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.

wait-for-import.ts
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}`));

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.

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.

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

One page (list) or every template (listAll). q matches part of the name.

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

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.

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

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.

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