Send SMS with Node.js

Send text messages from Node.js with coss.sms.send(), test every outcome in a sandbox, then go live with a registered number and track delivery.

This guide sends an SMS from Node.js (22+) with the coss SDK: first in a sandbox, where nothing is sent or billed, then live from your own registered number.

Install the SDK

npm install coss

Create an API key in your project's Development environment (a coss_test_… sandbox key), or run npx coss-cli init, and set it as COSS_API_KEY. The client reads it when you don't pass apiKey.

Send an SMS from Node.js

send-sms.ts
import {  } from "coss";

const  = new ({ : .. });

const { : ,  } = await ..({
  : "+14155550123",
  : "+15005550006",
  : "Your Acme order #1042 has shipped.",
});

if () .(., .);
else .(., .); // "queued"

The call returns HTTP 202 with status: "queued"; a background worker hands the message to the carrier. Methods return { data, error } and never throw for API or network failures (errors).

from and to are in E.164 form: +, the country code, then the number, without spaces or dashes (+14155550199, not (415) 555-0199). A to that isn't a phone number is refused with 422 invalid_phone_number.

Test SMS without sending real texts

Sandbox keys accept any from number, skip the number, country and plan checks, and simulate what a carrier does. Statuses, events, webhooks and logs all work. These numbers simulate an outcome; any other number is delivered:

See the SMS simulator.

What a live SMS send needs

Live (coss_live_…) keys send only from your organization's own numbers:

  1. A paid plan. Free organizations can use sandboxes only (plans).
  2. A number. Owners and admins buy a local or toll-free number on the dashboard's organization SMS page.
  3. An approved registration. US carriers only deliver application-to-person SMS from registered numbers: local numbers go through US A2P 10DLC (one brand and campaign for the organization), toll-free numbers through toll-free verification. coss.com submits both for you; reviews usually take a few days. See numbers and registration.
  4. An allowed country. Organizations start with the US and Canada; toll-free numbers only send there (countries).

coss.sms.numbers.list() returns each number with its registration_status and can_send. A live send from a number that isn't yours fails with sender_not_found, from one whose registration isn't approved with sender_not_ready, and to a country you don't allow with country_not_allowed (all 422). See sending SMS for the rest.

Segments and encoding

Carriers deliver and bill SMS in segments. A body made only of GSM-7 characters fits 160 characters in one segment (153 per segment when longer). One emoji or curly quote, like the one below, makes the whole message UCS-2: 70 characters in one segment (67 when longer). A body over 10 segments is refused. The message's segments and encoding say how it was counted:

const { :  } = await ..({
  : "+14155550123",
  : "+14155550101",
  : "Your table’s ready at Acme Bistro.",
});
.(?., ?.); // 1 "ucs2"

Live messages are billed per segment at the destination country's rate once they reach a carrier; failed, suppressed and canceled ones cost nothing. See pricing.

Avoid duplicate texts with idempotency keys

The SDK sets an idempotency key on every send and reuses it on retries. Pass your own, tied to the event, so a job that runs twice doesn't text twice: the same key returns the first message.

await ..(
  { : "+14155550123", : "+14155550101", : "Your Acme order #1042 has shipped." },
  { : "order-1042-shipped" },
);

Track delivery status with webhooks

Add a webhook endpoint for the sms.* events in the dashboard and verify each request with verifyWebhook. Payloads name the message but never include its text.

server.ts
import {  } from "node:http";
import {  } from "coss";

(async (, ) => {
  let  = "";
  for await (const  of )  += ;
  try {
    const  = await (, ., ..!);
    if (. === "sms.delivered") .("delivered", ..);
    if (. === "sms.undelivered" || . === "sms.failed") {
      .(.., ..?.);
    }
    .(200).("ok");
  } catch {
    .(400).("invalid signature");
  }
}).(3000);

Not every carrier reports delivery, so a message can stay sent. You can also poll with coss.sms.get(id) and coss.sms.listEvents(id) (statuses).

Handle STOP and opt-outs

When someone replies STOP (or UNSUBSCRIBE, CANCEL, END, QUIT and a few more), coss.com's SMS provider sends the confirmation carriers require and their number is suppressed in every live environment. Sends to it then fail with opted_out or suppressed and aren't billed; START removes the opt-out. Listen for sms.opted_out to update your own records, or ask coss.sms.suppressions.check({ phone_number }) before a send.

Opt-out and carrier-filtering rates count toward your reputation: text only people who asked, and say who you are in the first message.

Next steps

Last updated