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

Sender 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 does:

  • validate number and sender formats locally,
  • report a provider’s refusal of your sender as a ProviderRejectedError with category: "sender" or "account",
  • turn STOP, START, and HELP replies into events,
  • let you block sends with beforeSend.

SMS SDK 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-specific rules such as quiet hours or sender ID registration,
  • check whether a sender is registered. The doctor CLI marks registration as “not verified”.

Sender types

Sender What to arrange Typical use
US and Canada long code (10DLC) A2P 10DLC brand and campaign registration with your provider before carriers accept application traffic. Transactional and conversational messages at moderate volume.
Toll-free number Toll-free verification with your provider. 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 require 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 records it. Keep your own suppression list and check it in beforeSend. See STOP, HELP, and opt-outs.
  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 restrictions 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 }) => {
    if (await db.suppressions.has(message.to)) {
      return { kind: "reject", reason: "Recipient opted out." };
    }
    return { kind: "allow" };
  },
});

Every send now checks your suppression list first. For a suppressed recipient, send() throws PolicyRejectedError and sends nothing.

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 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, so its sender and account problems arrive as category: "request". See Plivo.

Provider documentation

Next steps