# SMS SDK > One TypeScript SDK for SMS providers. Send with Twilio, Telnyx, Plivo, Vonage, Bandwidth, or Sinch through one typed API, with safe fallback and zero runtime dependencies. Reach for SMS SDK (`@opencoredev/sms-sdk`) when a TypeScript server needs to send or receive transactional SMS through Twilio, Telnyx, Plivo, Vonage, Bandwidth, or Sinch with one API, or switch between them. Install with `npm install @opencoredev/sms-sdk` and import each provider from its own subpath, such as `@opencoredev/sms-sdk/twilio`. - `send()` resolves only when a provider accepted the message. It throws `ProviderRejectedError` when the provider refused it and `HandoffUnknownError` when the outcome is unknown; never resend after `HandoffUnknownError`. - Fallback to another provider is off until you set `fallback: "on-known-rejection"`. - `parseSmsWebhook()` from `@opencoredev/sms-sdk/webhooks` verifies the request before reading it and returns one event shape for every provider. - `memory()` from `@opencoredev/sms-sdk/testing` sends nothing, for tests. Every page below is also available as Markdown: append `.md` to its URL. ## Getting started - [Overview](https://www.sms-sdk.com/getting-started/overview): SMS SDK sends and receives transactional SMS through Twilio, Telnyx, Plivo, Vonage, Bandwidth, or Sinch with one typed TypeScript API. - [Installation](https://www.sms-sdk.com/getting-started/installation): Install @opencoredev/sms-sdk, check runtime requirements, and import only the adapters you use. - [Quick start](https://www.sms-sdk.com/getting-started/quick-start): Send your first SMS through Twilio with SMS SDK in three steps. - [How sending works](https://www.sms-sdk.com/getting-started/how-sending-works): The three outcomes of sms.send(), the order a send runs in, and every default with the option that changes it. ## Providers - [Choose a provider](https://www.sms-sdk.com/providers/overview): Pick an SMS provider for SMS SDK: a quick decision table, support status, capability matrix, and sender types for Twilio, Telnyx, Plivo, Vonage, Bandwidth, and Sinch. - [Twilio](https://www.sms-sdk.com/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://www.sms-sdk.com/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://www.sms-sdk.com/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://www.sms-sdk.com/providers/vonage): Send and receive SMS through the Vonage Messages API with the SMS SDK vonage() adapter: JWT vs Basic auth, senders, provider options, signed webhooks, and error mapping. - [Bandwidth](https://www.sms-sdk.com/providers/bandwidth): Send SMS through the Bandwidth Messaging API v2 with the SMS SDK bandwidth() adapter, and receive delivery and inbound callbacks behind Basic authentication. - [Sinch](https://www.sms-sdk.com/providers/sinch): Send and schedule SMS through the Sinch SMS API with the SMS SDK sinch() adapter, and receive delivery reports and inbound messages with Basic or HMAC callback authentication. - [Registration and consent](https://www.sms-sdk.com/providers/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. ## Sending - [Send a message](https://www.sms-sdk.com/sending/send-a-message): Call sms.send(), read the result, handle errors by whether a retry is safe, choose a sender, and use MMS, scheduling, and provider options. - [Fallback and retries](https://www.sms-sdk.com/sending/fallback-and-retries): Retry rate limits and fall back to a second provider, only when the first provider proved it did not take the message. - [Prevent duplicate sends](https://www.sms-sdk.com/sending/idempotency): Use idempotency keys and a store so a retried job does not send the same SMS twice, and know what to do when the outcome is unknown. - [Message length and cost](https://www.sms-sdk.com/sending/length-and-cost): Check a message with sms.validate() before you send, see how GSM-7 and UCS-2 change the segment count, and why the estimate is not a price. ## Receiving - [Receive webhooks](https://www.sms-sdk.com/receiving/webhooks): Receive delivery status updates and inbound texts from any provider as verified SmsEvent objects, in Next.js, Hono, or Bun.serve. - [Webhook security](https://www.sms-sdk.com/receiving/webhook-security): How SMS SDK verifies Twilio, Telnyx, Plivo, Vonage, Bandwidth, and Sinch webhooks, and how to fix verification behind a proxy. - [STOP, HELP, and opt-outs](https://www.sms-sdk.com/receiving/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. ## Testing and examples - [Test without a provider](https://www.sms-sdk.com/testing/local-testing): Test SMS code without a provider account or network: the memory() adapter, scripted failures, mockFetch, and signed webhook requests. - [Examples](https://www.sms-sdk.com/testing/examples): Runnable SMS SDK examples in the repository: tests with the memory adapter, a Twilio send, provider fallback, and a webhook handler. ## Switching providers - [Switch providers](https://www.sms-sdk.com/migration/switch-providers): Move SMS sending from one provider to another with SMS SDK: provision the sender, swap the adapter, move webhooks, run both during cutover, and keep a rollback path. - [Migrate from the Twilio SDK](https://www.sms-sdk.com/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. ## Advanced - [Block and log sends](https://www.sms-sdk.com/advanced/policy-and-hooks): Block sends with beforeSend, such as to people who opted out, and log or meter every attempt with hooks that never see phone numbers or message text. - [Share idempotency across servers](https://www.sms-sdk.com/advanced/multiple-instances): Prevent duplicate sends across servers, workers, and serverless functions with a shared IdempotencyStore that reserves keys atomically. - [Build your own adapter](https://www.sms-sdk.com/advanced/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 test runner. - [Contributing and support](https://www.sms-sdk.com/advanced/contributing): Where to ask questions about SMS SDK, how to report bugs and security issues, how to set up the repository and run the tests, and how to propose a new provider. ## Reference - [createSmsClient](https://www.sms-sdk.com/reference/create-sms-client): createSmsClient(options): every SmsClientOptions field, its default, and the SmsClient methods it returns. - [send()](https://www.sms-sdk.com/reference/send): sms.send(input, options): SmsSendInput and SmsSendResult fields, SendAttempt, the order of checks, and the errors it throws. - [validate() and encoding](https://www.sms-sdk.com/reference/validate): sms.validate(input), the segment and encoding helpers (estimateSegments, isGsm7, SEGMENT_LIMITS), and the phone number and redaction utilities. - [Errors](https://www.sms-sdk.com/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://www.sms-sdk.com/reference/webhook-events): @opencoredev/sms-sdk/webhooks: parseSmsWebhook options per provider, the SmsEvent union, keyword helpers, and signature verify helpers. - [Testing helpers](https://www.sms-sdk.com/reference/testing): @opencoredev/sms-sdk/testing: memory(), outcome helpers, mockFetch(), signed webhook request builders, and the adapter contract harness. - [Idempotency store](https://www.sms-sdk.com/reference/idempotency-store): The IdempotencyStore interface, its record states, the reserve and finalize contract, and memoryIdempotencyStore(). - [Adapter contract](https://www.sms-sdk.com/reference/adapter-contract): The SmsAdapter interface and its types: SmsCapabilities, ProviderOptionsSpec, AdapterMessage, SmsSender, SendContext, AdapterSendOutcome, and RejectionCategory. - [Doctor CLI](https://www.sms-sdk.com/reference/doctor-cli): sms-sdk doctor: check provider configuration without sending, preview encoding, and send one confirmed live message. - [Changelog](https://www.sms-sdk.com/reference/changelog): Release history for @opencoredev/sms-sdk. ## Agent resources - [llms-full.txt](https://www.sms-sdk.com/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://www.sms-sdk.com/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://www.sms-sdk.com/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://www.sms-sdk.com/openapi.json. - [MCP server](https://www.sms-sdk.com/mcp): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: https://www.sms-sdk.com/.well-known/mcp.json - [Agent skills](https://www.sms-sdk.com/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes. - [API catalog](https://www.sms-sdk.com/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [AI catalog](https://www.sms-sdk.com/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs). - [agent-readability.json](https://www.sms-sdk.com/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://www.sms-sdk.com/sitemap.xml): Every indexable page URL with its last-modified date.