# SMS SDK > One TypeScript SDK for SMS providers. Send with Twilio, Telnyx, Plivo, or Vonage through one typed API, with safe fallback and zero runtime dependencies. Use SMS SDK (`@opencoredev/sms-sdk`) to send transactional SMS from TypeScript through Twilio, Telnyx, Plivo, or Vonage with one API. Install with `npm install @opencoredev/sms-sdk`. It has no runtime dependencies and never retries or falls back after an ambiguous provider outcome. ## Getting started - [Overview](https://sms-sdk.vercel.app/getting-started/overview): SMS SDK sends and receives transactional SMS through Twilio, Telnyx, Plivo, or Vonage with one typed TypeScript API. - [Installation](https://sms-sdk.vercel.app/getting-started/installation): Install @opencoredev/sms-sdk, check runtime requirements, and import only the adapters you use. - [Quick start](https://sms-sdk.vercel.app/getting-started/quick-start): Send your first SMS through Twilio with SMS SDK in three steps. - [Important defaults](https://sms-sdk.vercel.app/getting-started/important-defaults): What SMS SDK does when you pass no options: fallback, retries, timeouts, idempotency, webhooks, and the option that changes each. - [Why SMS SDK](https://sms-sdk.vercel.app/getting-started/why-sms-sdk): SMS SDK vs the Twilio, Telnyx, Plivo, and Vonage SDKs: when each is the better fit, with a feature comparison and code. ## Sending - [Sending overview](https://sms-sdk.vercel.app/sending/overview): How sms.send() decides between accepted, rejected, and unknown, and which page covers each part of sending. - [Send your first SMS](https://sms-sdk.vercel.app/sending/send-your-first-sms): Call sms.send(), read the SmsSendResult, and handle each error by whether a retry is safe. - [Senders and E.164 numbers](https://sms-sdk.vercel.app/sending/senders-and-e164): Format recipients as E.164 and choose a sender: phone number, short code, alphanumeric sender ID, or messaging service. - [Validation and encoding](https://sms-sdk.vercel.app/sending/validation-and-encoding): Check a message locally with sms.validate() before you pay for a send: E.164, sender, capabilities, encoding, and segments. - [Segments and billing](https://sms-sdk.vercel.app/sending/segments-and-billing): How SMS SDK estimates GSM-7 and UCS-2 segments, why one emoji changes the count, and why the estimate is not a price. - [MMS, scheduling, and validity](https://sms-sdk.vercel.app/sending/mms-and-scheduling): Send media, schedule a message, set how long a provider keeps trying, and set a per-message status callback, with each provider's limits. - [Retries and fallback](https://sms-sdk.vercel.app/sending/retries-and-fallback): Configure rate-limit retries and safe fallback to a second provider. SMS SDK never retries or fails over after an unknown outcome. - [Idempotency](https://sms-sdk.vercel.app/sending/idempotency): Use idempotency keys and a store so a retried job does not send the same SMS twice, and know where exactly-once ends. - [Policy checks and hooks](https://sms-sdk.vercel.app/sending/policy-and-hooks): Block sends with beforeSend, such as to suppressed recipients, and log or meter every attempt with redacted hooks. ## Receiving - [Receiving overview](https://sms-sdk.vercel.app/receiving/overview): Turn provider webhooks into verified, normalized SmsEvent objects for delivery status, inbound messages, and opt-outs. - [Delivery status webhooks](https://sms-sdk.vercel.app/receiving/delivery-status-webhooks): Learn whether an accepted message was delivered: configure status callbacks and map each provider's statuses to SmsEvent types. - [Inbound SMS](https://sms-sdk.vercel.app/receiving/inbound-sms): Receive replies to your numbers as verified message.received events, with sender, recipient, text, and media URLs. - [STOP, HELP, and opt-outs](https://sms-sdk.vercel.app/receiving/stop-help-and-opt-outs): Record opt-outs from STOP replies, answer HELP, and block sends to suppressed recipients. SMS SDK helps; compliance stays your app's job. - [Webhook security](https://sms-sdk.vercel.app/receiving/webhook-security): How SMS SDK verifies Twilio, Telnyx, Plivo, and Vonage webhook signatures, and how to fix verification behind a proxy. - [Duplicates and ordering](https://sms-sdk.vercel.app/receiving/duplicates-and-ordering): Providers deliver webhooks more than once and out of order. Deduplicate with dedupeKey and never move a message's status backward. ## Providers - [Providers overview](https://sms-sdk.vercel.app/providers/overview): Compare the Twilio, Telnyx, Plivo, and Vonage adapters: support status, sender types, MMS, scheduling, webhooks, and limits. - [Twilio](https://sms-sdk.vercel.app/providers/twilio): Send and receive SMS and MMS through Twilio Programmable Messaging with the SMS SDK twilio() adapter: setup, senders, webhooks, errors, and limits. - [Telnyx](https://sms-sdk.vercel.app/providers/telnyx): Send and receive SMS and MMS through the Telnyx Messaging API v2 with the SMS SDK telnyx() adapter: setup, senders, webhooks, errors, and limits. - [Plivo](https://sms-sdk.vercel.app/providers/plivo): Send and receive SMS and MMS through the Plivo Message API with the SMS SDK plivo() adapter: setup, senders, webhooks, errors, and partial-support limits. - [Vonage](https://sms-sdk.vercel.app/providers/vonage): Send and receive SMS through the Vonage Messages API with the SMS SDK vonage() adapter: Basic vs JWT auth, regions, webhooks, errors, and partial-support limits. - [Build a provider adapter](https://sms-sdk.vercel.app/providers/writing-an-adapter): Add an SMS provider by implementing the SmsAdapter contract, mapping responses to accepted, rejected, or unknown, and checking it with the contract harness. ## Guides - [Local testing](https://sms-sdk.vercel.app/guides/local-testing): Test SMS code without a provider account or network: the memory() adapter, scripted failures, mockFetch, and signed webhook requests. - [Use with Next.js](https://sms-sdk.vercel.app/guides/nextjs): Send SMS from Next.js route handlers and server actions, and receive verified provider webhooks in the App Router. - [Use with Hono and Bun](https://sms-sdk.vercel.app/guides/hono-and-bun): Send SMS and receive verified webhooks from a Hono app or a plain Bun.serve server. - [Deploy with multiple instances](https://sms-sdk.vercel.app/guides/multiple-instances): Share idempotency across servers, workers, and serverless functions with an atomic IdempotencyStore, and know what still needs manual reconciliation. - [Sender registration and consent](https://sms-sdk.vercel.app/guides/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. ## Migration - [Migrate from the Twilio SDK](https://sms-sdk.vercel.app/migration/migrate-from-twilio): Move SMS sending and webhooks from the twilio npm package to SMS SDK while staying on Twilio: concept mapping, code, and a rollback path. - [Switch Twilio to Telnyx](https://sms-sdk.vercel.app/migration/switch-twilio-to-telnyx): Move SMS sending from Twilio to Telnyx with SMS SDK: provision the sender, swap the adapter, move webhooks, and cut over gradually with a rollback path. ## Reference - [createSmsClient](https://sms-sdk.vercel.app/reference/create-sms-client): createSmsClient(options): every SmsClientOptions field, its default, and the SmsClient methods it returns. - [send()](https://sms-sdk.vercel.app/reference/send): sms.send(input, options): SmsSendInput and SmsSendResult fields, SendAttempt, the order of checks, and the errors it throws. - [validate()](https://sms-sdk.vercel.app/reference/validate): sms.validate(input): SmsValidationResult fields, ValidationIssue codes, and what local validation cannot check. - [Errors](https://sms-sdk.vercel.app/reference/errors): Every SMS SDK error class with its code, retrySafe value, when it is thrown, and what to do about it. - [Webhooks and events](https://sms-sdk.vercel.app/reference/webhook-events): @opencoredev/sms-sdk/webhooks: parseSmsWebhook options per provider, the SmsEvent union, keyword helpers, and signature verify helpers. - [Adapter contract](https://sms-sdk.vercel.app/reference/adapter-contract): The SmsAdapter interface and its types: SmsCapabilities, ProviderOptionsSpec, AdapterMessage, SmsSender, SendContext, AdapterSendOutcome, and RejectionCategory. - [Idempotency store](https://sms-sdk.vercel.app/reference/idempotency-store): The IdempotencyStore interface, its record states, the reserve and finalize contract, and memoryIdempotencyStore(). - [Testing helpers](https://sms-sdk.vercel.app/reference/testing): @opencoredev/sms-sdk/testing: memory(), outcome helpers, mockFetch(), signed webhook request builders, and the adapter contract harness. - [Encoding and utilities](https://sms-sdk.vercel.app/reference/encoding-and-utilities): estimateSegments, isGsm7, the GSM-7 tables, SEGMENT_LIMITS, isE164, maskPhoneNumber, redactText, and the other root helpers. - [Doctor CLI](https://sms-sdk.vercel.app/reference/doctor-cli): sms-sdk doctor: check provider configuration without sending, preview encoding, and send one confirmed live message. ## Examples - [Examples](https://sms-sdk.vercel.app/examples/overview): Runnable SMS SDK examples in the repository: a Twilio send, provider fallback, a webhook handler, and tests with the memory adapter. ## Community - [Contributing](https://sms-sdk.vercel.app/community/contributing): Report issues, propose providers, and send pull requests to SMS SDK: setup, test commands, and the rules every change follows. - [Changelog](https://sms-sdk.vercel.app/community/changelog): Release history for @opencoredev/sms-sdk. - [Support](https://sms-sdk.vercel.app/community/support): Where to ask questions about SMS SDK, report bugs, and report security issues, and which questions belong with your SMS provider. ## Agent skills - [sms-sdk](https://sms-sdk.vercel.app/.well-known/agent-skills/sms-sdk/SKILL.md): Read the SMS SDK docs instead of answering from memory. One TypeScript SDK for SMS providers. Send with Twilio, Telnyx, Plivo, or Vonage through one typed API, with safe fallback and zero runtime dependencies. Use when a task involves SMS SDK: how it works, how to set it up or configure it, or its API. ## Agent resources - [llms-full.txt](https://sms-sdk.vercel.app/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://sms-sdk.vercel.app/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://sms-sdk.vercel.app/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://sms-sdk.vercel.app/openapi.json. - [Agent skills](https://sms-sdk.vercel.app/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes. - [API catalog](https://sms-sdk.vercel.app/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [AI catalog](https://sms-sdk.vercel.app/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs). - [agent-readability.json](https://sms-sdk.vercel.app/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://sms-sdk.vercel.app/sitemap.xml): Every indexable page URL with its last-modified date.