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

Quick start

Send your first SMS through Twilio with SMS SDK in three steps.

By the end of this page, a server-side script sends one SMS through Twilio and prints the provider’s message ID.

You need a Twilio Account SID, Auth Token, and a Twilio number that can text your destination. Registering that number for 10DLC or toll-free is up to you. See Sender registration and consent.

1. Install

npm install @opencoredev/sms-sdk
pnpm add @opencoredev/sms-sdk
yarn add @opencoredev/sms-sdk
bun add @opencoredev/sms-sdk
nub add @opencoredev/sms-sdk
aube add @opencoredev/sms-sdk

2. Create the client

Set three environment variables on your server. Never send them to a browser.

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_FROM=+15550100001

Create the client in its own module so the rest of your app imports one instance:

import { createSmsClient, isE164 } from "@opencoredev/sms-sdk";
import { twilio } from "@opencoredev/sms-sdk/twilio";

const from = process.env.TWILIO_FROM;
if (!isE164(from)) {
  throw new Error("Set TWILIO_FROM to your Twilio number in E.164 format, such as +15550100001.");
}

export const sms = createSmsClient({
  adapters: [
    twilio({
      accountSid: process.env.TWILIO_ACCOUNT_SID ?? "",
      authToken: process.env.TWILIO_AUTH_TOKEN ?? "",
      from,
    }),
  ],
});

Creating the client makes no network request. A malformed Account SID or empty Auth Token makes twilio() throw a ConfigurationError at startup, not on the first send.

3. Send a message

import { isSmsError } from "@opencoredev/sms-sdk";
import { sms } from "./sms";

try {
  const result = await sms.send({
    to: "+14155550123", // replace with your own phone number
    body: "Hello from SMS SDK.",
    idempotencyKey: "quick-start:1",
  });
  console.log(`Accepted by ${result.provider}: ${result.providerId} (${result.delivery})`);
} catch (error) {
  if (isSmsError(error)) {
    console.error(error.code, error.message, `retrySafe: ${error.retrySafe}`);
  }
  throw error;
}

Run it with npx tsx --env-file=.env send.ts on Node.js or bun send.ts on Bun, which loads .env itself. It prints a line like Accepted by twilio: SM… (queued), and the text reaches your phone shortly after.

queued means Twilio accepted the message, not that the phone got it. Delivery is reported later by webhook.

If the send fails, read the error’s code and retrySafe. provider_auth means Twilio rejected the credentials. handoff_unknown means SMS SDK cannot tell whether Twilio accepted the message, so check the Twilio console before you resend. Errors lists every code.

Next steps