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