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/….
Preview — SMS sending is template-only today: every send names a built-in, Bird-provided template and supplies its variables. Free-form SMS — composing your own message body — is not yet generally available; a free-text send is rejected with a not-authorized error until your workspace is enabled for it.
Reading your messages, metrics, and events is open to every workspace.
The SMS app in the dashboard
In the dashboard, SMS is one of the channels in the sidebar's Products section. Its pages, and where each one's guide lives:
| Page | What it's for |
|---|---|
| Messages | Every message sent and received, with its per-message event timeline and delivery detail — see the SMS log |
| Templates | The built-in templates you can send — name, category, languages, and variables — see SMS templates |
| Metrics | Delivery rate, failure rate, accepted volume, segments, and spend over time — see Tracking & metrics |
How sending works
You send an SMS with POST /v1/sms/messages: one recipient, one message. Today you name a built-in template and supply its variables; Bird assembles the body. Bird validates the request, prices and queues it, and returns 202 Accepted with a message ID — delivery happens asynchronously from there. A 202 means Bird has durably accepted your send and is working on it; 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 messages in one call, POST /v1/sms/batches takes up to 100 independent messages.
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 (160 GSM-7 characters, or 70 if it contains emoji or other non-GSM characters) is split and billed per segment. Sending SMS explains how the split works and how to keep messages to one segment.
- Why you send matters. Every message carries a category — transactional, marketing, authentication, or service — which drives opt-out (STOP) handling, quiet-hours rules, and per-country compliance. On a template send the category comes from the template.
Sending
Sending today is by template: pick a built-in template, supply its variables, and Bird assembles and sends the message. Sending SMS covers the send API in depth — recipients and senders, the body and its segment cap, categories, tags and metadata, the async 202 model, batch sends, and idempotent retries — including the free-text mode that is currently in preview.
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 with no sender registration, and checks the user's answer — expiry, attempt limits, and resend cooldowns included.
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 and receipt, its event timeline, segments, cost, and carrier detail.
- Tracking & 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.
Receiving
Inbound messages — replies and messages sent to your number — appear in the SMS log with a received status and an inbound direction, alongside your outbound traffic. Filter the log by direction to see one side at a time.
Next steps
| Page | What it covers |
|---|---|
| SMS templates | The built-in template catalogue and sending by template reference |
| Sending SMS | The send API — recipients, senders, body, segments, categories, tags |
| SMS log | Every message, its event timeline, segments, and cost |
| Tracking & 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 |