To send an SMS from Clojure, call clj-http to POST JSON to https://api.tryready.com/v1/messages with an X-API-Key header and an Idempotency-Key header. The body is a map with to, body and consent_attested. Return the status and decide what to do with it as plain data.

Clojure suits texting well, because a send is a function from a map to a map, and refusals are just values you can branch on. We make Ready, and the example uses only the one request shape we document.

Before you start

  • An API key from Ready, read from the environment.
  • A card on file and a number of your own ($2 a month).
  • Consent you can show. consent_attested is your statement that the recipient agreed to texts.
  • clj-http and cheshire (or jsonista) on your classpath.

Each segment is $0.0075 plus a $0.0045 carrier fee. See the pricing page.

The function

(ns app.texting
  (:require [clj-http.client :as http]
            [cheshire.core :as json]))

(defn send-text [to body idem-key]
  (let [res (http/post "https://api.tryready.com/v1/messages"
              {:headers {"X-API-Key" (System/getenv "READY_API_KEY")
                         "Idempotency-Key" idem-key}
               :content-type :json
               :body (json/generate-string
                       {:to to :body body :consent_attested true})
               :socket-timeout 15000
               :connection-timeout 10000
               :throw-exceptions false})]
    {:status (:status res)
     :ok? (<= 200 (:status res) 299)}))

Setting :throw-exceptions false matters. By default clj-http throws on 4xx and 5xx, and a refusal such as a quiet-hours 409 isn't an exception. It's an expected answer. Use E.164 numbers like +12125550199.

Branch on the result

(defn handle [{:keys [status]}]
  (cond
    (<= 200 status 299) :sent
    (= status 409)      :retry-after-window
    (= status 403)      :fix-request
    (>= status 500)     :retry-same-key
    :else               :give-up))
StatusMeaning
2xxAccepted
409 QUIET_HOURS_BLOCKThe window opens more than 6 hours from now; send again once it opens, or set hold_until_allowed
403 api_consent_attested_requiredNo attestation on the send
5xx or timeoutRetry with the same idempotency key

The quiet hours 409 guide explains the second row. Opted-out numbers are refused up front and aren't charged.

Concurrency without surprises

Use core.async or a bounded thread pool to send many texts, and cap concurrency so you don't hit the per-second limits covered in SMS API rate limits. Derive the idempotency key from your own record ID, such as order-1042-shipped, so replaying a stream after a crash doesn't text twice. The idea is explained in deterministic idempotency keys.

Frequently asked questions

Is there a Clojure client library for Ready? No, and you don't need one. A single http/post call with a JSON body covers the whole send.

Can I use http-kit or hato instead? Yes. Any HTTP client that can set headers and send a JSON body will do the same job.

How do I test without sending real texts? Use a test API key, which simulates sends. See the sandbox and test numbers guide.

Next step

Send one text to your own phone, then call send-text twice with the same key and check that one message arrives. The API quickstart shows how to get a key.

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