To send a text from R, build a request with httr2: point request() at https://api.tryready.com/v1/messages, add your key as an X-API-Key header, attach a JSON body with req_body_json(), and call req_perform(). No SMS package is needed, and httr2 already handles retries and timeouts for you.

We make Ready, so the example uses our REST API and only the request shape we document. R scripts often run on a schedule, against a data frame of people, which makes one problem likely: a script that fails halfway and gets rerun. The design below makes a rerun safe by giving each row a stable idempotency key.

What you need before the first request

  • An API key. Ready authenticates with an X-API-Key header. Keep it in ~/.Renviron as READY_API_KEY=... and read it with Sys.getenv(). Don't hard-code it in a script that lives in a repository.
  • A card and a number. A card on file and a number of your own are required to send. The number is $2 a month. To build first, create a test key (Settings, Developers, Environment: Test). It simulates every send with no card, number or charge.
  • Consent. Each request carries consent_attested = TRUE, your statement that the recipient agreed to receive texts. Filter your data frame down to people who did before you send.
  • Registration. An account can send up to 500 texts a month until its 10DLC registration is approved, and most approvals take 2 to 7 days. Our 10DLC explainer covers the why.

Each segment costs $0.0075 plus a $0.0045 carrier fee, and screening is extra when switched on.

Send one text

The endpoint is POST https://api.tryready.com/v1/messages. The body takes to in E.164 format (a 10-digit US number is treated as +1), body, and consent_attested.

library(httr2)

send_text <- function(to, body, key) {
  request("https://api.tryready.com/v1/messages") |>
    req_headers(
      `X-API-Key`       = Sys.getenv("READY_API_KEY"),
      `Idempotency-Key` = key
    ) |>
    req_body_json(list(
      to               = to,
      body             = body,
      consent_attested = TRUE
    )) |>
    req_timeout(20) |>
    req_retry(
      max_tries    = 4,
      is_transient = \(resp) resp_status(resp) %in% 429
    ) |>
    req_error(is_error = \(resp) FALSE) |>
    req_perform()
}

resp <- send_text("+12125550199", "Your order #1042 has shipped.",
                  uuid::UUIDgenerate())
resp_status(resp)
resp_body_string(resp)

A few choices in there are deliberate. req_body_json() serializes the list for you, so a name with a quote or a newline can't break the JSON, and single values go out as scalars rather than arrays. req_timeout(20) stops a stalled call from freezing a long script. And req_error(is_error = \(resp) FALSE) keeps a 4xx from throwing, so your loop can log it and move on. For the response fields and error bodies, use the messages API reference and the error codes page.

Retries without double-sending

When a request times out you don't know whether the text went out. Retrying blindly can text a customer twice, and duplicate texts collect opt-outs.

The Idempotency-Key header is the fix. Make one UUID per logical message, and send the same key on every attempt. req_retry() resends the same request object, headers included, so the key doesn't change between tries. A retried request with the same key doesn't send twice. What req_retry() can't protect you from is a second run of the whole script, which brings us to the data frame.

Text every row of a data frame

Create the keys once, save them to disk before the first send, log each row as it finishes, and let each run skip rows that already succeeded.

library(dplyr)

# Rerun-safe: the keys live in contacts-keyed.csv from the first run on.
src <- if (file.exists("contacts-keyed.csv")) "contacts-keyed.csv" else "contacts.csv"
contacts <- readr::read_csv(src) |> filter(consented)
if (!"key" %in% names(contacts)) contacts$key <- NA_character_
contacts <- contacts |>
  mutate(key = coalesce(key, vapply(seq_len(n()), \(i) uuid::UUIDgenerate(), "")))
readr::write_csv(contacts, "contacts-keyed.csv")  # save the keys before the first send

log <- "sent-log.csv"
done <- if (file.exists(log)) {
  prev <- readr::read_csv(log)
  prev$key[prev$status %in% 200:299]
} else character()

for (i in which(!contacts$key %in% done)) {
  Sys.sleep(0.2)  # a gentle pace; adjust to your account's throughput
  status <- tryCatch(
    resp_status(send_text(contacts$phone[i], contacts$message[i], contacts$key[i])),
    error = \(e) NA_integer_  # timeout or dropped connection: outcome unknown, same key next run
  )
  # one line per row, written as it finishes, so a crash loses nothing
  readr::write_csv(data.frame(key = contacts$key[i], status = status), log,
                   append = file.exists(log))
}

If the script dies halfway, run it again. It reads contacts-keyed.csv back, so every row keeps its original key, and it skips rows whose logged status is in the 200s. A row that timed out is retried with the same key, so it can't text anyone twice. The reasoning is covered in idempotency keys and duplicate texts and deterministic idempotency keys.

If the same message goes to many people, the bulk endpoint is one call per batch instead of one per row.

What to do with each status

StatusAction
2xxRecord it and move on.
4xx other than 429Don't retry. Fix the row or the account.
429req_retry() handles it. If it still fails, rerun later.
503Nothing was sent or charged, and the same key would replay the stored error. Rerun the row with a new key.
500 or 504Check GET /v1/messages before sending again. The message may have gone out.
409The recipient may be in quiet hours. Rerun once the window opens.

An API text in quiet hours is held only if the window opens soon. Otherwise it isn't sent and the API answers 409 QUIET_HOURS_BLOCK. Our post on handling the quiet hours 409 goes through it.

Next step

Run the single-send function with a test key and a made-up number like +12125550199. Check you get a 2xx, then try the data frame version on three rows and run it twice to confirm nothing sends again. Then add the card and number and switch to a live key. The API quickstart covers a first send and a webhook for replies.

Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.