Choose an API
Choose the right sms4sats API v2 payment and authentication model.
sms4sats exposes two SMS integration styles plus a dedicated email API. They share the same inventory provider but use different payment proofs and credentials.
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:
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:
Choose L402 when your agent or service can pay Lightning invoices programmatically and retrieve the settlement preimage. See the complete L402 guide.
Email API
Endpoint family:
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.
Product comparison
One-time SMS
Bearer-token
Hold settles after durable SMS; 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
Last updated