# SMS overview Bird SMS sends text messages through the same platform and the same API keys as [Bird Email](/docs/guides/email/overview). You call Bird with a `bk_{region}_…` key against your regional host (`https://us1.platform.bird.com` or `https://eu1.platform.bird.com`); Bird picks a route to the recipient's carrier, splits your text into billable segments, and reports each message through to a delivery receipt. One API, one set of credentials, per-channel endpoints under `/v1/sms/…`. You can send two kinds of message, and both are available to every workspace: **free-form text** you compose (with a sender and category you choose) and Bird's built-in **[templates](/docs/guides/sms/templates)**, which supply the body, category, and sender for you. Bird SMS is **outbound-only** today: Bird collects delivery receipts for what you send, but does not yet receive inbound messages, so replies (including STOP texts) are not captured. ## How sending works You send an SMS with `POST /v1/sms/messages`: one recipient, one message, carrying either your own `text` (plus a sender and category) or a `template` reference with its variable values. Bird validates the request and the destination, resolves the sender, and returns `202 Accepted` with a message ID; delivery happens asynchronously from there. The actual outcome (sent to the carrier, delivered, undelivered, failed, expired) arrives afterwards through [events and webhooks](/docs/guides/sms/events) and the message read endpoints. To send many independent messages in one call, use the [batch endpoint](/docs/guides/sms/sending-sms#batch-sending). Three ideas shape the whole API: - **A send is not a delivery.** The `202` means Bird accepted the message, not that a handset received it. Each message walks its own lifecycle (accepted, sent to the carrier, then a terminal receipt), and the delivery receipt can arrive seconds or minutes later. - **Text is billed in segments.** A message longer than one segment is split and billed per segment, and the per-segment capacity depends on the characters you use. [Sending SMS](/docs/guides/sms/sending-sms#segments-and-encoding) has the encoding rules and how to keep messages to one segment. - **Why you send matters.** Every message carries a [category](/docs/guides/sms/sending-sms#body-and-category) (`transactional`, `marketing`, `authentication`, or `service`), which tells Bird and carriers why you're sending and is how per-country compliance rules (opt-out policy, quiet hours) are applied as they roll out. On a template send the category comes from the template. One prerequisite before your first send: enable the destination countries you serve under **SMS → Destinations**. The allowlist is default-deny and typically starts with only your organization's home country enabled; a send to any other country is rejected. [Sending SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) covers it. If the message you're sending is a one-time passcode, consider [Bird Verify](/docs/guides/verify/overview) instead of composing it yourself: it generates the code, delivers it over SMS or email, and checks the user's answer, with expiry, attempt limits, and resend cooldowns included. ## The SMS app in the dashboard In the [dashboard](/docs/knowledge-base/getting-started/dashboard-tour), SMS is one of the products in the sidebar. Its pages, and where each one's guide lives: | Page | What it's for | | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [**Messages**](https://bird.com/dashboard/w/sms/messages) | Every message sent, with its per-message event timeline and delivery detail. Guide: [SMS log](/docs/guides/sms/sms-log) | | [**Templates**](https://bird.com/dashboard/w/sms/templates) | The built-in templates you can send: name, category, languages, and variables. Guide: [SMS templates](/docs/guides/sms/templates) | | [**Metrics**](https://bird.com/dashboard/w/sms/metrics) | Delivery rate, failure rate, accepted volume, segments, and spend over time. Guide: [SMS metrics](/docs/guides/sms/tracking-and-metrics) | | [**Destinations**](https://bird.com/dashboard/w/sms/destinations) | The countries your workspace may send to; enable a destination before sending there. Guide: [Sending SMS](/docs/guides/sms/sending-sms) | ## Visibility Every message produces an event timeline (accepted, sent, delivered, or a failure) plus the segment count and cost once it's priced: - **[SMS log](/docs/guides/sms/sms-log)**: the per-message view in the dashboard. Every send, its event timeline, segments, cost, and carrier detail. - **[SMS metrics](/docs/guides/sms/tracking-and-metrics)**: the aggregate delivery rate, failure rate, accepted volume, segment count, spend, and delivery latency across everything you send. - **[Events](/docs/guides/sms/events)**: the SMS event vocabulary, the message lifecycle, and webhook delivery to your own endpoints. ## Next steps | Page | What it covers | | ---------------------------------------------------- | --------------------------------------------------------------------- | | [Sending SMS](/docs/guides/sms/sending-sms) | The send API: destinations, senders, body, segments, categories, tags | | [SMS templates](/docs/guides/sms/templates) | The built-in template catalog and sending by template reference | | [SMS log](/docs/guides/sms/sms-log) | Every message, its event timeline, segments, and cost | | [SMS metrics](/docs/guides/sms/tracking-and-metrics) | Delivery rate, failure rate, segments, spend, and latency | | [Events](/docs/guides/sms/events) | The SMS event types and webhook delivery | | [Webhooks & events](/docs/guides/webhooks) | Endpoint setup, signature verification, retries, and replay | | [Verify overview](/docs/guides/verify/overview) | One-time passcodes over SMS and email, sent and checked by Bird |