> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS

> POST /v1/sms

Sends a single SMS via your Twilio number. Useful for one-off messages, status updates, or reminders that do not need a phone call.

## Request

```bash theme={null}
curl -X POST https://api.nixflex.com/v1/sms \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_125207e452f8714a",
    "to": "+447386172392",
    "from_number": "+447446466847",
    "message": "Reminder: your appointment is tomorrow at 2pm. Reply YES to confirm."
  }'
```

## Body parameters

| Field         | Type   | Required | Notes                                                                                                                                                                |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`    | string | Yes      | Agent that owns this SMS — its `system_prompt` handles any replies                                                                                                   |
| `to`          | string | Yes      | Recipient in E.164                                                                                                                                                   |
| `from_number` | string | Yes      | Your imported Twilio number                                                                                                                                          |
| `message`     | string | Yes      | Message text. **600 chars recommended** for reliable carrier delivery. Twilio hard cap is 1600. See [SMS length guide](/sms/send-sms#sms-length-and-deliverability). |

## Response

`201 Created`:

```json theme={null}
{
  "status": "sent",
  "to": "+447386172392",
  "from": "+447446466847"
}
```

Status updates come asynchronously via Twilio status callbacks. Final status (`delivered`, `failed`, `undelivered`) reflects in the message record within \~30 seconds.

## Reply behaviour

If the recipient replies, the agent automatically answers using its `system_prompt`. There is no separate reply-handling system or context field.

**Best practice:** if recipients might reply to your SMS, include the relevant context (what you sent, what you expect them to ask) in the agent `system_prompt` before sending. See [Send SMS concept page](/sms/send-sms) for details.

## Errors

| Code                          | Cause                                |
| ----------------------------- | ------------------------------------ |
| `from_number_not_owned`       | `from_number` is not in your account |
| `message_too_long`            | Message over 1600 chars              |
| `sms_not_supported_in_region` | US number without A2P 10DLC          |
| `recipient_unsubscribed`      | Recipient previously sent STOP       |