# `bird sms send`

## Usage

```bash
bird sms send [flags]
```

## Description

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").

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.

## Examples

```bash
# print the body shape (no credentials needed)
bird sms send --example

# the body it prints:
```

```json
{
  "category": "authentication",
  "from": "+15557654321",
  "metadata": {
    "user_id": "usr_12345"
  },
  "tags": [
    {
      "name": "campaign",
      "value": "signup"
    }
  ],
  "text": "Your verification code is 123456.",
  "to": "+15551234567"
}
```

```bash
# send by template with variable values
bird sms send --to +15551234567 --template bird_otp_verification --parameters '{"code":"123456"}'

# preview the resolved request without sending
bird sms send --body-file body.json --dry-run
```

## Options

#### Routing

| 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. Omit to let Bird choose |

#### Content

| 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 name (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                                      |

#### Labels & metadata

| Name                | Description                    |
| ------------------- | ------------------------------ |
| `--tag <key=value>` | Tag as name=value; repeatable  |
| `--metadata`        | Arbitrary JSON metadata object |

#### Request

| 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 |

#### Options

| Name                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--response-schema` | Print the fields this command returns, then exit |

## Related

| Name                                            | Description        |
| ----------------------------------------------- | ------------------ |
| [`bird sms get`](/docs/cli/reference/sms-get)   | Get an SMS message |
| [`bird sms list`](/docs/cli/reference/sms-list) | List SMS messages  |