Java: Send SMS with an Android SMS Gateway API

Sending SMS from Java through an Android SMS gateway API is HttpClient + JSON. Do not brand a thin wrapper as a Complete SDK, and do not copy query-string ?key= from a 2018 gist.

Service pricing is based on device count and total SMS sent through the gateway. Contract: API docs. Sibling runtimes: Go, C. Retry: backoff.

UUID.randomUUID() in a retry interceptor is how you double-text a one-time code and still pass unit tests.

HttpClient, not a Java SDK

Prefer a worker (JMS, SQS, virtual threads + queue) over blocking a servlet on the radio. You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance.

Send table

Canonical HTTPS JSON

curl -X POST "https://app.sms-gateway.app/api/v1/messages" \
  -H "Authorization: Bearer $SMS_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1b0c8a-9d2e-4c77-9f5a-2b6d1e0f4a83" \
  -d '{"to":["+14155552671"],"text":"Your verification code is 481920","type":"sms"}'

Java illustration

// Illustration — REST HTTPS/JSON, not a Java SDK product.
// Confirm fields in https://docs.sms-gateway.app/ before production.
HttpRequest req = HttpRequest.newBuilder(URI.create("https://app.sms-gateway.app/api/v1/messages"))
    .header("Authorization", "Bearer " + System.getenv("SMS_GATEWAY_API_KEY"))
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", idem) // pin to user+challenge, not UUID.randomUUID() per retry
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .timeout(Duration.ofSeconds(30))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());

Docs win if this drifts. No Maven SKU.

Stable Idempotency-Key

Pin to user+challenge. OTP. Webhooks.

Checklist

• No “Java SDK” in the README.
• Timeouts set.
• HMAC inbound.
• OTP isolated.

Next steps

Canary curl, then the JVM. Pair the phone.