To send an SMS from Elixir, use Req to POST JSON to your provider's REST API, and wrap the call in an Oban worker so retries and unique jobs come for free. Phoenix needs nothing special for sending, only for receiving replies.
We make Ready, so the example uses the Ready REST API and only the request shape we document. The retry story is the interesting part in Elixir, because Oban already gives you most of it.
One function with Req
defmodule MyApp.Sms do
@url "https://api.tryready.com/v1/messages"
def send(to, body, key) do
Req.post(@url,
json: %{to: to, body: body, consent_attested: true},
headers: [
{"x-api-key", System.fetch_env!("READY_API_KEY")},
{"idempotency-key", key}
],
receive_timeout: 15_000,
retry: false
)
end
end retry: false is deliberate. Req can retry on its own, but you want one place that decides what's retryable, and for texts that place is the job, not the HTTP client. to is E.164. Set consent_attested to true only when the recipient agreed to texts.
An Oban worker that retries safely
defmodule MyApp.SmsWorker do
use Oban.Worker, queue: :sms, max_attempts: 5,
unique: [period: 3600, keys: [:key]]
@impl true
def perform(%Oban.Job{args: %{"to" => to, "body" => body, "key" => key}}) do
case MyApp.Sms.send(to, body, key) do
{:ok, %{status: s}} when s in 200..299 -> :ok
{:ok, %{status: 429}} -> {:error, :rate_limited}
{:ok, %{status: s}} when s >= 500 -> {:error, {:server, s}}
{:ok, %{status: 409, body: %{"code" => "idempotency_in_progress"}}} -> {:error, :in_progress}
{:ok, %{status: s, body: b}} -> {:cancel, {s, b}}
{:error, reason} -> {:error, reason}
end
end
end Enqueue with the key generated once: %{to: to, body: body, key: Ecto.UUID.generate()} |> MyApp.SmsWorker.new() |> Oban.insert(). The key travels in the job args, so every attempt sends the same Idempotency-Key, and a repeated key means the request isn't sent twice. The unique option stops you from inserting the same logical message twice on your side.
A 409 idempotency_in_progress means the first attempt with this key is still running, so it is an error Oban retries with the same key, not a cancel. {:cancel, ...} is for permanent failures such as a bad number or an opted-out contact. Oban won't retry them, and the failure stays visible in the job table. After a 504, or a code ending in OUTCOME_UNKNOWN, check GET /v1/messages before you resend. The retries guide has the full decision table.
Receiving replies in Phoenix
Replies arrive as webhooks. In a controller, read the raw body before parsing so you can verify the signature, answer 200 fast and hand the work to another Oban job.
def create(conn, _params) do
{:ok, raw, conn} = Plug.Conn.read_body(conn)
# verify the signature against raw, then enqueue
MyApp.InboundWorker.new(%{"raw" => raw}) |> Oban.insert()
send_resp(conn, 200, "ok")
end Event names and the signature header live in the docs quickstart, and our webhook signing post explains the verify-then-acknowledge order. In Phoenix, cache the raw body with a custom body reader so it's still there after Plug.Parsers.
What each piece does
- Req makes the call and nothing else.
- Oban owns retries, attempts and uniqueness.
- The job args carry the idempotency key.
- Phoenix only receives webhooks.
FAQ
Do I need an Elixir SMS library?
No. Req plus a small module is enough, and it keeps the request shape visible in your code.
Why not let Req retry?
Req's retry doesn't know your business rules. A quiet-hours refusal or an opted-out number should never be retried, and a timeout needs the same idempotency key. Putting the policy in the job keeps it in one place.
How do I test it?
Use a test key, which simulates every send with no card, number or charge. For unit tests, stub the MyApp.Sms module with Mox so no request leaves the test.
The short version
Req for the call, Oban for the retries, one idempotency key created at enqueue time. The messages API docs cover every field.
Cost and registration
A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.