To send an SMS from Lua, POST a JSON body to https://api.tryready.com/v1/messages with an X-API-Key header and an Idempotency-Key header. In OpenResty use lua-resty-http so the call doesn't block the worker. The body carries to, body and consent_attested.
Lua appears in texting work through gateways and edge code: an OpenResty or Kong layer that decides something is worth a text, or a game server that needs to alert a player. We make Ready, and the example uses only the request shape we document.
Before you start
- An API key from Ready, stored in an environment variable or your gateway's secrets store, never in a file under version control.
- A card on file and a number of your own ($2 a month).
- Consent you can show for each recipient.
lua-resty-httpandcjson(both standard in OpenResty).
Each segment costs $0.0075 plus the $0.0045 carrier fee. See the pricing page.
The code
local http = require "resty.http"
local cjson = require "cjson"
local function send_text(to, body, idem_key)
local httpc = http.new()
httpc:set_timeouts(5000, 10000, 15000) -- connect, send, read (ms)
local res, err = httpc:request_uri("https://api.tryready.com/v1/messages", {
method = "POST",
headers = {
["Content-Type"] = "application/json",
["X-API-Key"] = os.getenv("READY_API_KEY"),
["Idempotency-Key"] = idem_key,
},
body = cjson.encode({ to = to, body = body, consent_attested = true }),
ssl_verify = true,
})
if not res then return nil, err end -- network error: retry with the same key
return res.status
end In OpenResty, read the key with os.getenv after declaring it with the env directive in nginx.conf. Don't call this inside a request that a user is waiting on. Use ngx.timer.at(0, ...) to send in the background so the response isn't delayed. Use E.164 numbers like +12125550199.
Handling the status
| Status | Meaning | Action |
|---|---|---|
| 2xx | Accepted | Log it |
409 QUIET_HOURS_BLOCK | Window opens more than 6 hours from now | Send again once it opens |
403 api_consent_attested_required | Attestation missing | Fix the body |
| nil or 5xx | Transient | Retry with backoff, same key |
Opted-out numbers are refused up front and not charged. The retries and failure handling post has a full table.
Protect the gateway
A gateway that can text is a gateway that can run up a bill. Add a rate limit per client with lua-resty-limit-req, a daily cap on texts, and a cooldown per alert key. Fair-share rate limiting for multi-tenant SMS covers the design. Also keep the API key out of logs, which the key security guide explains.
Frequently asked questions
Does this block the nginx worker? Not with lua-resty-http, which uses cosockets. Plain socket.http would block.
Can I use lua-http outside OpenResty? Yes. The request is the same outside OpenResty, and only the HTTP client library changes.
How do I send to many numbers? Use POST /v1/messages/bulk, which takes a list of numbers, with at most 100 numbers per call.
Next step
Send one text from a timer on a staging gateway, then trigger the same alert twice and check that the cooldown and idempotency key stop the second text. The API quickstart shows how to create a key.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.