> 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/getting-started/api-options.md).

# Choose an API

Choose the right sms4sats API v2 payment and authentication model.

sms4sats exposes two SMS integration styles plus a dedicated email API. Choose the payment proof and credentials that fit your integration.

## Bearer-token API

**Recommended for most integrations.**

Endpoints:

```
/v2/receive-sms/*
/v2/rent-numbers/*
```

Creation returns a BOLT11 hold invoice and a one-time `accessToken`. Poll and cancellation requests use:

```http
Authorization: Bearer <accessToken>
```

Choose this API when:

* your wallet does not expose payment preimages;
* you want payment release instead of a separate refund payment;
* you need UUID-based idempotent creation;
* you are integrating a browser, mobile client, conventional backend, or bot.

## L402 API

Endpoints:

```
/v2/l402/*
```

Creation intentionally returns `402 Payment Required`, an invoice, and a macaroon. After payment, use the macaroon and payment preimage as a scoped credential:

```http
Authorization: L402 <serialized-macaroon>:<preimage-hex>
```

Choose L402 when your agent or service can pay Lightning invoices programmatically and retrieve the settlement preimage. See the complete [L402 guide](/api-reference/l402.md).

## Email API

Endpoint family:

```
/v2/emails/*
```

Email activation orders use hold invoices. For the protected flow documented here, creation must include `X-SMS4SATS-Email-Capability: v1`; the response then returns the bearer order token required for polling, reordering, and cancellation. Domain availability and pricing are queried before creation. See [Email Activations](/api-reference/emails.md).

## Product comparison

| Product          | API          | Payment outcome                                                                   | Manual cancellation                                             |
| ---------------- | ------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| One-time SMS     | Bearer-token | Hold settles after SMS fulfillment; otherwise releases                            | After 3 minutes when eligible                                   |
| Number rental    | Bearer-token | Hold settles after successful number allocation                                   | Unpaid orders only; any paid rental is not manually cancellable |
| One-time SMS     | L402         | Standard payment; eligible failure/cancel refunds to a supplied no-amount invoice | After 3 minutes when eligible                                   |
| Number rental    | L402         | Standard payment; no rental refund flow                                           | Not supported after payment                                     |
| Email activation | Email API    | Hold settles when fulfillment succeeds; failure paths attempt release             | After 2 minutes when eligible                                   |