Skip to content
SMS SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Registration and consent

What you must set up with providers and carriers before sending: 10DLC, toll-free verification, short codes, sender IDs, consent, and opt-out records.

Carriers want to know who is sending, what kind of messages they send, and that recipients agreed to get them. You arrange that with your provider, outside SMS SDK. This page lists what to set up and where each provider documents its current rules.

What SMS SDK does and does not do

SMS SDK validates number and sender formats locally, reports a provider’s refusal of your sender as a ProviderRejectedError with category: "sender" or "account", turns STOP, START, and HELP replies into events, and lets you block sends with beforeSend.

It does not:

  • buy numbers, register 10DLC brands or campaigns, submit toll-free verification, or apply for short codes,
  • collect or store consent, keep an opt-out list, or send required confirmation replies,
  • know country rules such as quiet hours or sender ID registration,
  • check whether a sender is registered. The doctor CLI reports registration as “not verified”.

Sender types

Sender What to arrange Typical use
US and Canada long code (10DLC) A2P 10DLC brand and campaign registration before carriers accept application traffic. Transactional and conversational messages at moderate volume.
Toll-free number Toll-free verification. Unverified toll-free traffic is blocked or filtered in the US and Canada. Notifications and support.
Short code A short code application and carrier approval, which can take weeks. High volume, marketing, one-time codes.
Alphanumeric sender ID Allowed only in some countries, some with pre-registration. Not supported in the US or Canada. Recipients cannot reply. One-way notifications outside North America.
Messaging service or pool The numbers inside it still need the registration their type requires. Sender selection and scaling handled by the provider.

Register with every provider you send through. A 10DLC campaign on Twilio does not cover a number on Telnyx. With fallback configured, the fallback provider’s sender needs its own registration, or carriers reject or filter its sends.

Your app is responsible for:

  1. Getting consent before sending, in the form the destination requires, and storing proof: who, when, how, and for what kind of messages.
  2. Honoring opt-outs on every provider. Only the provider whose number got the STOP knows about it, so keep your own suppression list and check it in beforeSend.
  3. Answering HELP with who you are and how to get support, where required. Some providers reply automatically for some sender types, so check before adding your own reply.
  4. Following content and timing rules, such as quiet hours and limits on certain message categories.
import { createSmsClient } from "@opencoredev/sms-sdk";
import { twilio } from "@opencoredev/sms-sdk/twilio";
import { db } from "./db";

export const sms = createSmsClient({
  adapters: [
    twilio({
      accountSid: process.env.TWILIO_ACCOUNT_SID ?? "",
      authToken: process.env.TWILIO_AUTH_TOKEN ?? "",
      from: { messagingService: process.env.TWILIO_MESSAGING_SERVICE_SID ?? "" },
    }),
  ],
  beforeSend: async ({ message }) =>
    (await db.suppressions.has(message.to)) ? { kind: "reject", reason: "Recipient opted out." } : { kind: "allow" },
});

Every send checks your suppression list first. For a suppressed recipient, send() throws PolicyRejectedError and sends nothing. Recording opt-outs and answering HELP are covered in STOP, HELP, and opt-outs.

How registration problems show up

You see Likely cause
ProviderRejectedError, category: "sender" The sender is not provisioned, not registered for this use, or not allowed for this destination.
ProviderRejectedError, category: "account" Trial restrictions, geographic permissions, balance, or spend limits.
message.filtered webhook A carrier or the provider blocked the message as spam or for its content, often because of missing registration.
message.undelivered with a carrier error code Many causes, including unregistered traffic. Check the provider’s error dictionary.

Plivo does not document its error body, and SMS SDK maps only a few Bandwidth and Sinch codes, so sender and account problems on those providers usually arrive as category: "request". See each provider’s error codes: Plivo, Bandwidth, Sinch.

Provider documentation

Next steps