SMS overview
Bird SMS sends text messages through the same platform and the same API keys as Bird Email. 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, 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 and the message read endpoints. To send many independent messages in one call, use the batch endpoint.
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 has the encoding rules and how to keep messages to one segment.
- Why you send matters. Every message carries a 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 covers it.
If the message you're sending is a one-time passcode, consider Bird Verify 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, 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, accepted volume, segments, and spend 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, segment count, spend, 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 |
| 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, segments, spend, 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 |