> 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-sms.md).

# Send SMS Overview

Send SMS using the original SMS4Sats API contract, with Lightning invoices or a prepaid satoshi balance.

This section is only for **sending SMS**, not receiving verification codes, renting numbers, or email activations.

The send API preserves the legacy endpoint names, `X-API-Key` authentication, satoshi balances, and JSON responses on the canonical API origin:

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

## Choose a payment mode

| Mode            | How it works                                                                     | API key                                      |
| --------------- | -------------------------------------------------------------------------------- | -------------------------------------------- |
| Pay per message | Create a send order, pay its Lightning invoice, then poll its status             | Not required unless `immediate` is requested |
| Prepaid         | Top up a balance once, then request `immediate: true` sends against that balance | Required                                     |

Send is a separate legacy-compatible contract. It does **not** use receive-SMS bearer tokens or L402 macaroons. Do not prepend `/v2/receive-sms` to these paths.

## Endpoint overview

| Method | Path                       | Purpose                                                  |
| ------ | -------------------------- | -------------------------------------------------------- |
| `POST` | `/fund`                    | Create a Lightning invoice to top up an API-key balance  |
| `GET`  | `/balance`                 | Read the balance in satoshis                             |
| `GET`  | `/history`                 | Read paid funding history                                |
| `POST` | `/createsendorder`         | Create a send order, paid by invoice or existing balance |
| `GET`  | `/orderstatus?orderId=...` | Read payment and SMS-send status                         |

Start with [Top up & balances](https://docs.sms4sats.com/send-sms/top-up.md), then [Send a message & track delivery](https://docs.sms4sats.com/send-sms/send.md).

## API-key handling

For existing integrations, reuse your original `X-API-Key`: the send account remains associated with that key and its original balance records. There is no conversion to a new receive-SMS account.

For a new integration, choose a cryptographically random secret identifier, such as a UUID. Keep it private: possession of the key authorizes spending its prepaid balance. Send it only as the `X-API-Key` header, never in a public URL.

Keys must be nonempty, have no surrounding whitespace, be at most 256 UTF-8 bytes, and exclude these characters (`.`, `#`, `$`, `[`, `]`, `/`, `\`) and control characters.

{% hint style="warning" %}
Send only to recipients who consented to receive your messages. Existing anti-spam checks remain in place. An accepted API request is not proof of handset delivery; poll the order status.
{% endhint %}
