To send an SMS from Kotlin, POST JSON to your messaging provider's REST endpoint with Ktor's HttpClient, put the API key in a header, and read the status code before you trust the result. You don't need a vendor SDK, and the same function works in a Ktor server, a Spring service or a plain coroutine job.

We make Ready, so the example uses the Ready REST API and only the request shape we document. If you're on the JVM but not Kotlin, our Java guide is the sibling to this one.

The client and one send function

Create one HttpClient for the whole process and reuse it. Building a client per request throws away connection pooling and leaks threads.

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.serialization.json.*

val http = HttpClient(CIO) {
    install(HttpTimeout) { requestTimeoutMillis = 15_000 }
}

suspend fun sendSms(to: String, text: String, key: String): Pair<Int, String> {
    val payload = buildJsonObject {
        put("to", to)
        put("body", text)
        put("consent_attested", true)
    }
    val res = http.post("https://api.tryready.com/v1/messages") {
        header("X-API-Key", System.getenv("READY_API_KEY"))
        header("Idempotency-Key", key)
        contentType(ContentType.Application.Json)
        setBody(payload.toString())
    }
    return res.status.value to res.bodyAsText()
}

to is E.164, like +12125550199. consent_attested is your promise the recipient agreed to texts, so only set it to true when you hold that consent. Using buildJsonObject means a quote or emoji in the message can't break your JSON the way string templates do.

Retries that don't double-text

Make the idempotency key once per logical message, store it with the job, and reuse it on every attempt. A repeated key means a repeated request isn't sent twice, which is what makes a retry after a timeout safe.

suspend fun sendWithRetry(to: String, text: String, key: String): Pair<Int, String> {
    var wait = 500L
    repeat(4) { attempt ->
        val result = try { sendSms(to, text, key) } catch (e: HttpRequestTimeoutException) { null }
        val retryable = result == null || result.first == 429 || result.first == 500 ||
            (result.first == 409 && result.second.contains("idempotency_in_progress"))
        if (!retryable || attempt == 3) return result ?: (0 to "timeout")
        delay(wait)
        wait *= 2
    }
    return 0 to "unreachable"
}

This is the shape, not the whole policy. A 503 was not sent, but the same key replays that stored error, so resend it under a new key. After a 504, or a code ending in OUTCOME_UNKNOWN, check GET /v1/messages before sending again. The retries guide sorts every failure into retry, park or hold, and the idempotency post explains the lost-response case.

Where to put the call in a Ktor server

Don't call the API inside the request handler that a user is waiting on. Write a row to your own table (or push to a channel), return, and let a worker coroutine send. That keeps a slow carrier hop out of your p99 and gives the retry loop a place to live. The queue design post covers the table layout.

ConcernDo this
Client lifetimeOne HttpClient, closed on shutdown
TimeoutSet requestTimeoutMillis explicitly
API keyEnvironment variable, never in the repo
Idempotency keyCreated with the job, reused on retry
BodybuildJsonObject, not string templates

FAQ

Do I need a Kotlin SMS SDK?

No. The API is plain HTTPS and JSON, so Ktor, OkHttp or the JDK client all work. A function like sendSms above is usually all an app needs, and it adds no dependency to audit.

Does this work in a Kotlin Multiplatform or Android app?

The code runs, but don't ship the API key inside a mobile app. Anyone can pull it out of the binary. Send from your backend, and let the app call your backend.

How do I test it without sending real texts?

Use a test key. It simulates every send with no card, number or charge, and our sandbox guide covers the options.

The short version

One shared client, a JSON builder, a stable idempotency key and a small backoff loop. Everything else is queueing, and that belongs in your own database. The full request reference is in the messages API docs.

Cost and registration

A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, 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.