SMS overview
Bird SMS sends text messages through the same platform and API keys as Bird Email. 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 its delivery receipt. SMS endpoints start with /v1/sms/.
You can send free-form text with a sender and category you choose, or use one of Bird's built-in templates, which supplies the body, category, and sender. Bird also receives replies to your numbers. It stores each inbound message alongside your sends and emits sms.received. When a reply matches a supported opt-out keyword such as STOP, Bird also records a sender-and-subscriber suppression. See Opt-outs and keywords for coverage and configuration.
How sending works
Send an SMS with POST /v1/sms/messages: one recipient and one message, carrying either your own text with a sender and category or a template reference with its variable values. Bird validates the request and destination, resolves the sender, and returns 202 Accepted with a message ID. Delivery then happens asynchronously. Follow the outcome through events and webhooks or the message read endpoints. To send many independent messages in one call, use the batch endpoint.
Three ideas shape the whole API:
- Sending and delivery are separate stages. A 202 means Bird accepted the message. The handset receives it only after the message advances through the carrier and reaches a terminal receipt. That 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. Character limits has the encoding rules, the full character set, and how to keep messages to one segment.
- Why you send matters. Every message carries a category: transactional, marketing, authentication, or service. Bird and carriers use it to understand the message's purpose. On a template send, the category comes from the template.
Before your first send, enable the destination countries you serve under SMS > Destinations. The default-deny allowlist starts with only your organization's home country enabled. Bird rejects a send to any other country. Sending SMS covers this prerequisite.
For one-time passcodes, consider Bird Verify instead of composing the message yourself. Verify generates and delivers the code over SMS or email, checks the answer, and enforces expiry, attempt limits, and resend cooldowns.
The SMS app in the dashboard
In the dashboard, SMS is one of the products in the sidebar. Its pages, and where each one's guide lives:
| Page | What it's for |
|---|---|
| Messages | Every message sent, with its per-message event timeline and delivery detail. Guide: SMS log |
| Templates | The built-in templates you can send: name, category, languages, and variables. Guide: SMS templates |
| Metrics | Delivery rate, failure rate, and accepted volume over time. Guide: SMS metrics |
| Destinations | The countries your workspace may send to; enable a destination before sending there. Guide: 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: the per-message view in the dashboard. Every send, its event timeline, segments, cost, and carrier detail.
- SMS metrics: the aggregate delivery rate, failure rate, accepted volume, and delivery latency across everything you send.
- Events: the SMS event vocabulary, the message lifecycle, and webhook delivery to your own endpoints.
Next steps
| Page | What it covers |
|---|---|
| Sending SMS | The send API: destinations, senders, body, segments, categories, tags |
| Character limits | GSM-7 and UCS-2 encoding, per-segment limits, and the 12-segment cap |
| SMS templates | The built-in template catalog and sending by template reference |
| SMS log | Every message, its event timeline, segments, and cost |
| SMS metrics | Delivery rate, failure rate, and latency |
| Events | The SMS event types and webhook delivery |
| Webhooks & events | Endpoint setup, signature verification, retries, and replay |
| Verify overview | One-time passcodes over SMS and email, sent and checked by Bird |