> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/send-sms/send.md).

# Send a Message & Track Delivery

Send an SMS with the legacy-compatible API and poll its delivery status.

## Request fields

`POST https://api.sms4sats.com/createsendorder`

| Field        | Type    | Required | Meaning                                                                                                         |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `phone`      | string  | Yes      | Recipient number in international format, including country code; E.164 with `+` is recommended                 |
| `message`    | string  | Yes      | Nonempty SMS text, at most **140 UTF-16 code units** (some characters, including many emoji, consume two)       |
| `immediate`  | boolean | No       | Set to `true` to spend the balance belonging to `X-API-Key`; omit or use `false` to receive a Lightning invoice |
| `webhookUrl` | string  | No       | Publicly reachable HTTPS URL for SMS-status updates                                                             |

The limit applies to UTF-16 code units, not SMS segments. Invalid numbers and messages rejected by anti-spam checks cannot be sent. The API determines the price; caller-supplied price fields do not override it.

## Option A: pay per message

```bash
curl -sS -X POST 'https://api.sms4sats.com/createsendorder' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+12025550123","message":"Your requested notification."}'
```

The number is an example; replace it with your own consenting recipient.

```json
{
  "status": "OK",
  "orderId": "<order-id>",
  "payreq": "<bolt11-invoice>"
}
```

Pay the amount specified in `payreq`, then poll `/orderstatus`. The returned invoice is authoritative.

## Option B: prepaid immediate sending

First [top up and confirm your balance](https://docs.sms4sats.com/send-sms/top-up.md).

```bash
curl -sS -X POST 'https://api.sms4sats.com/createsendorder' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_SECRET_API_KEY' \
  --data '{"phone":"+12025550123","message":"Your requested notification.","immediate":true}'
```

```json
{
  "status": "OK",
  "orderId": "<order-id>",
  "payreq": "paid"
}
```

`payreq: "paid"` means this order uses the prepaid flow; there is no second invoice to pay. Recheck `/balance` for the resulting debit.

Do not blindly retry a timed-out send: it may already have reached the provider. The legacy send contract has no caller-provided idempotency key. Preserve order IDs and reconcile status before retrying.

## Poll send status

Polling requires **no API key**: possession of the order ID permits lookup. Treat order IDs as private. Use the exact order ID returned by the API; do not construct one yourself.

Invalid input, a missing order, or a lookup exception returns HTTP **400** with `{ "status": "error", "reason": "..." }`:

| `reason`                    | Meaning                  |
| --------------------------- | ------------------------ |
| `valid orderId is required` | Missing or invalid ID    |
| `order does not exist`      | No matching stored order |
| `server error`              | Status lookup failed     |

```bash
curl -sS 'https://api.sms4sats.com/orderstatus?orderId=ORDER_ID'
```

Example after the provider has created the SMS:

```json
{
  "status": "OK",
  "paid": true,
  "smsStatus": "created",
  "timestamp": 1700000000000
}
```

Fields vary with the order's state. Delivery updates can change `smsStatus` to values such as `sent`, `delivered`, or `undelivered`. A send failure can expose an `error` field.

**Important:** `status: "OK"`, `paid: true`, or `payreq: "paid"` alone does not prove delivery. Read `smsStatus` and `error`. The inherited send flow can record a provider error even when the create response is `OK`; do not treat that as a new retry authorization.

If you supplied `webhookUrl`, delivery-status updates use the same public status shape. Your handler should return promptly and tolerate repeated updates. Use `/orderstatus` to confirm payment and delivery state; receiving a notification alone is not payment confirmation.

## Common errors

| HTTP status | `reason`                                                                 |
| ----------- | ------------------------------------------------------------------------ |
| `400`       | `missing x-api-key header` when requesting prepaid sending without a key |
| `400`       | `invalid x-api-key header`                                               |
| `500`       | `missing required parameters`                                            |
| `500`       | `message can not be longer than 140 characters`                          |
| `500`       | `phone number validation failed`                                         |
| `500`       | `message rejected as spam`                                               |
| `500`       | `spam detection failed, please try again later.`                         |
| `500`       | `Not enough balance.`                                                    |
| `500`       | `Failed to create order. Try again later.`                               |
| `500`       | `backend error` (invoice mode)                                           |
| `500`       | `backend invoice error` (invoice mode)                                   |
| `500`       | `unable to save data` (invoice mode)                                     |
| `500`       | `unable to create invoice` (invoice mode)                                |

The status codes and wording above intentionally retain the legacy contract, including its `500` validation responses.
