Send an SMS message to one recipient
Sending is outbound and irreversible: it reports "accepted", not "delivered" —
read the message back with "bird sms get" to confirm delivery. Send free text with
--text (and --category), or a stored template with --template (browse them with
"bird sms templates list"). A workspace template needs --from with a sender the
workspace owns; a built-in template selects its sender, so omit --from.
Build the request from flags, a JSON SMSMessageSendRequest body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.
# print the body shape (no credentials needed)
bird sms send --example
# the body it prints:
{
"category": "authentication",
"from": "+15557654321",
"metadata": {
"user_id": "usr_12345"
},
"options": {
"smart_encoding": true
},
"tags": [
{
"name": "campaign",
"value": "signup"
}
],
"text": "Your verification code is 123456.",
"to": "+14155550100"
}
# send by template with variable values
bird sms send --to +14155550100 --template bird_otp_verification --parameters '{"code":"123456"}'
# preview the resolved request without sending
bird sms send --body-file body.json --dry-run
| Name | Description |
|---|
--to | Recipient phone number in E.164 format (e.g. +15551234567) |
--from | Sender: an E.164 number, an alphanumeric sender ID, or a short code. Required with --text and workspace templates; omit with built-in templates |
| Name | Description |
|---|
--text | Free-text message body (mutually exclusive with --template) |
--category | Content classification: transactional, marketing, authentication, or service (required with --text) |
--template | Send by a stored template: its id (smt_…) or slug (mutually exclusive with --text) |
--language | Template language as a BCP-47 tag (e.g. fr); template sends only |
--parameters | Template variable values as a JSON object; template sends only |
| Name | Description |
|---|
--tag <key=value> | Tag as name=value; repeatable |
--metadata | Arbitrary JSON metadata object |
| Name | Description |
|---|
--body-file | Read the JSON request body from this file; "-" reads stdin |
--example | Print a complete example request body, then exit |
--dry-run | Print the resolved request without sending it, then exit |
--idempotency-key | Deduplication key; a retry with the same key won't act twice |
| Name | Description |
|---|
--smart-encoding | Replace characters outside the GSM-7 alphabet (curly quotes, dashes, ellipses) with their closest equivalent, which often lowers the segment count and the cost. Off by default, since it alters the body you wrote; pass --smart-encoding to opt this send in |
--response-schema | Print the fields this command returns, then exit |