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-http and cjson (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

StatusMeaningAction
2xxAcceptedLog it
409 QUIET_HOURS_BLOCKWindow opens more than 6 hours from nowSend again once it opens
403 api_consent_attested_requiredAttestation missingFix the body
nil or 5xxTransientRetry 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.