SMS

coss.sms sends text messages from your organization's phone numbers, reports what carriers do with them, and receives the replies. It uses the same API key, webhooks, logs and sandbox environments as email.

const { data: sms, error } = await coss.sms.send({
  from: "+14155550123",
  to: "+14155550199",
  body: "Your Acme code is 482913",
});

Numbers are in E.164 form: +, the country code, then the number, without spaces. Sends return HTTP 202 with status: "queued"; a background worker hands the message to the carrier. Follow it with coss.sms.get() or the sms.* webhooks.

Quick start

1. Try it in a sandbox. Sandbox (coss_test_…) keys accept any from number and simulate every message: send to +15005550006 and it is delivered, to +15005550001 and it fails with invalid_number. The SMS simulator has a number for each outcome. Nothing is sent or billed.
2. Choose a paid plan. Live SMS is available on paid plans (plans); Free organizations can use sandboxes.
3. Get a number and register it. On the dashboard's organization SMS page, owners and admins buy a local or toll-free number and register it with the carriers: US A2P 10DLC for local numbers, toll-free verification for toll-free ones. Reviews usually take a few days. See numbers and registration.
4. Send with a live key. Once the registration is approved, live (coss_live_…) keys send from the number to the countries your organization allows (the US and Canada to start with).

// Which numbers can send live messages now?
const { data: numbers } = await coss.sms.numbers.list();
for (const number of numbers?.data ?? []) {
  console.log(number.phone_number, number.kind, number.registration_status, number.can_send);
}

What's in it

Messages are kept for 45 days and received messages for 30 days (see data retention). Webhook payloads never include the text: read it with coss.sms.get() or coss.sms.received.get().