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/….
SMS is in early access and rolls out per workspace. If your workspace isn't enabled yet, the SMS endpoints and the dashboard's SMS pages return a not-authorized error; the rest of this section describes how they behave once you're in.
The SMS app in the dashboard
In the dashboard, SMS is one of the workspace's channel apps. 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 |
| 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 body, one message. 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.
Sending
Sending SMS covers the send API in depth: the recipient and sender formats, the body and its segment cap, categories, tags and metadata, the async 202 model, batch sends, and idempotent retries.
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 |
|---|---|
| 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 |