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 cossCreate 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
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:
| To | Simulates | Status |
|---|---|---|
+15005550006 | Delivered | delivered |
+15005550001 | A number that can't get SMS | failed (invalid_number) |
+15005550004 | Filtered by the carrier | undelivered (carrier_filtered) |
+15005550009 | A recipient who opted out | failed (opted_out) |
+15005550008 | Delivered, then a reply | delivered, then sms.received |
See the SMS simulator.
What a live SMS send needs
Live (coss_live_…) keys send only from your organization's own numbers:
- A paid plan. Free organizations can use sandboxes only (plans).
- A number. Owners and admins buy a local or toll-free number on the dashboard's organization SMS page.
- 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.
- 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.
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
- Sending SMS: statuses, failures, scheduling, suppressions and limits
- Receiving SMS: replies and the
sms.receivedwebhook - Verify phone numbers in a Next.js app
- Webhooks and SMS pricing
Last updated