To send an SMS from Haskell, build a JSON body with aeson, set an X-API-Key header and an Idempotency-Key header, and POST it to https://api.tryready.com/v1/messages with http-conduit. A 2xx status means the text was accepted, and anything else maps to a case in your own sum type.

Haskell's strength here is making refusals explicit. A send can succeed, wait for quiet hours, be refused for missing consent or fail transiently, and a sum type forces every caller to handle each case. We make Ready, and the example uses only the request shape we document.

Before you start

  • An API key from Ready, read with lookupEnv.
  • A card on file and a number of your own, at $2 a month.
  • Consent you can show, since consent_attested is your promise the person agreed.
  • http-conduit, aeson and text in your cabal or stack file.

A text costs $0.0075 plus a $0.0045 carrier fee per segment. See pricing.

The code

{-# LANGUAGE OverloadedStrings #-}
module Texting where

import Data.Aeson (object, (.=), encode)
import qualified Data.ByteString.Char8 as B
import Network.HTTP.Simple
import System.Environment (lookupEnv)

data Outcome = Sent | WaitForWindow | FixRequest | RetrySameKey | GiveUp
  deriving (Show, Eq)

sendText :: String -> String -> String -> IO Outcome
sendText to msg idemKey = do
  Just key <- lookupEnv "READY_API_KEY"
  req0 <- parseRequest "POST https://api.tryready.com/v1/messages"
  let req = setRequestHeader "X-API-Key" [B.pack key]
          $ setRequestHeader "Idempotency-Key" [B.pack idemKey]
          $ setRequestBodyLBS (encode (object
              [ "to" .= to, "body" .= msg, "consent_attested" .= True ]))
          $ setRequestHeader "Content-Type" ["application/json"] req0
  res <- httpNoBody req
  pure (classify (getResponseStatusCode res))

classify :: Int -> Outcome
classify s
  | s >= 200 && s < 300 = Sent
  | s == 409            = WaitForWindow
  | s == 403            = FixRequest
  | s >= 500            = RetrySameKey
  | otherwise           = GiveUp

httpNoBody is fine when you only need the status, and httpLBS returns the body if you want the error detail. Wrap the call in try for network exceptions and map those to RetrySameKey. Use E.164 numbers like +12125550199.

What each outcome means

OutcomeStatusDo this
Sent2xxRecord it
WaitForWindow409 QUIET_HOURS_BLOCKThe recipient's window is more than 6 hours away; resend when it opens
FixRequest403 api_consent_attested_requiredCorrect the body
RetrySameKey5xx or timeoutRetry with backoff and the same key

Opted-out numbers and Ban list numbers are refused up front and not charged. See handling the quiet hours 409 and the error codes docs.

Idempotency and concurrency

Derive the key from a record you already have, such as invoice-884-overdue. Then a retried job, a restarted worker or a replayed event stream can't send twice. For many sends, use async with a bounded pool, and stay under the limits in SMS API rate limits. The reasoning is in idempotency and duplicate texts.

Frequently asked questions

Do I need a Haskell SDK? No. http-conduit and aeson cover the whole call, so there is nothing else to install.

Can I use wreq or req instead? Yes. The request is the same whichever client builds it.

How do I read replies? Replies arrive through a webhook endpoint that you host and secure yourself. See inbound webhooks.

Next step

Run sendText against your own phone twice with one key, and confirm a single message arrives. The API quickstart shows how to create a key.

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