# 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 skills

- [sms-sdk](https://www.sms-sdk.com/.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, Vonage, Bandwidth, or Sinch 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://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.