To send SMS from Google Cloud Run, run a small HTTP service that receives Pub/Sub push messages and calls POST /v1/messages for each one. Return a 2xx to acknowledge the message, return an error to have Pub/Sub deliver it again, and send an Idempotency-Key header created once per text so a redelivery never sends twice.
That last point is the heart of it. Pub/Sub delivers at least once, so your handler will occasionally see a message it already processed. The SMS call is the one step you can't undo, so it has to be safe to repeat. This post covers the handler, the ack rules, the secret, and the settings that keep retries sane.
How the pieces fit
A producer (your app, a scheduled job, another service) publishes a message to a topic. A push subscription POSTs each message to your Cloud Run service. The service calls Ready, then answers with a status code that tells Pub/Sub what to do next.
| Your response | What Pub/Sub does |
|---|---|
| 200, 201, 202, 204 | Treats the message as acknowledged and stops |
| Any other status, or no answer before the ack deadline | Treats it as not acknowledged and delivers it again after a backoff |
| Repeated failures with a dead-letter topic configured | Moves the message to the dead-letter topic after the set number of attempts |
So the decision for every Ready response is: should this message be delivered again? That's what the handler encodes.
The request to Ready
Base URL https://api.tryready.com, header X-API-Key, and a JSON body with to (E.164; a 10-digit US number is treated as +1), body and consent_attested. Set consent_attested to true only when the recipient agreed to texts. Leave from out and Ready picks the number: the one this contact already texts with, otherwise your number closest to their area code.
An Express handler for the push endpoint
The publisher creates a UUID once, when the text is first requested, and puts it in the message attributes as textKey. The message data is a base64 JSON payload with the number and the text.
const express = require("express");
const app = express();
app.use(express.json());
app.post("/pubsub", async (req, res) => {
const msg = req.body?.message;
if (!msg?.data || !msg.attributes?.textKey) {
return res.status(204).end(); // malformed: acknowledge and drop, retrying can't fix it
}
const { to, body } = JSON.parse(Buffer.from(msg.data, "base64").toString());
try {
const r = await fetch("https://api.tryready.com/v1/messages", {
method: "POST",
headers: {
"X-API-Key": process.env.READY_API_KEY,
"Content-Type": "application/json",
"Idempotency-Key": msg.attributes.textKey,
},
body: JSON.stringify({ to, body, consent_attested: true }),
signal: AbortSignal.timeout(8000),
});
if (r.ok) return res.status(204).end();
if (r.status === 429 || r.status >= 500) {
return res.status(503).end(); // not acknowledged: Pub/Sub redelivers
}
console.error("send refused", r.status, msg.attributes.textKey, await r.text());
return res.status(204).end(); // refused: redelivery would get the same answer
} catch (err) {
return res.status(503).end(); // timeout or network error: redeliver with the same key
}
});
app.listen(process.env.PORT || 8080); Three details are worth copying. A malformed message is acknowledged, because nothing about a retry would improve it, and an endless loop on bad data is a classic way to fill a dead-letter topic. A refused send (a 4xx) is acknowledged and logged for the same reason. And a timeout returns a 503, so Pub/Sub tries again with the same textKey.
Why the key must travel with the message
Pub/Sub gives every message a messageId, and it stays the same across redeliveries of that message. That's tempting as an idempotency key, but it isn't a UUID you control: if the producer publishes the same logical text twice (its own retry, a double click), those are two Pub/Sub messages with two IDs, and both would send.
A UUID created by the producer when the text is first requested, then stored with the record and carried in attributes.textKey, covers both cases. One UUID per message, reused on every retry and every redelivery. Don't create it inside the handler, because each delivery would get a fresh one. Our post on idempotency and duplicate texts has the longer reasoning.
Store the key as a secret
Keep the Ready API key in Secret Manager and expose it to the service as an environment variable from the secret when you deploy, either in the console under the service's variables and secrets or in your deploy config. The service account that runs the service needs access to that one secret and nothing more. Don't bake the key into the container image or commit it to source.
Also lock down the endpoint. Create the push subscription with a service account and have Cloud Run require authentication, so only Pub/Sub can call /pubsub. Otherwise anyone who finds the URL can make your service send texts. See API key security and rotation for rotation.
Settings that keep retries sane
- Ack deadline: set it longer than your request timeout plus a margin. An 8-second call with a 10-second deadline leaves almost no room.
- Retry policy: use exponential backoff on the subscription so a Ready outage doesn't produce a retry storm.
- Dead-letter topic: set one with a maximum delivery attempts count, and alert on it. When a message lands there, check
GET /v1/messagesbefore replaying it, so you don't send a text that actually went out. - Concurrency: Cloud Run can scale out quickly, but texting has a per-second ceiling per registered campaign (roughly 1 to 4 segments per second for a fresh standard campaign, tens for higher tiers). Cap the service's max instances and per-instance concurrency so a large backlog doesn't hammer the limit.
For throttling and queue patterns in general, read SMS queue design for platforms.
What Ready handles for you
Opted-out numbers and Ban-list numbers are refused up front and not charged, so the handler above logs and acknowledges them. An API text in the recipient's quiet hours is held only if the window opens within 6 hours; otherwise it isn't sent and the API answers 409 QUIET_HOURS_BLOCK. Treat that as a "send later" case: publish the message again with a delay once the window opens, using a new text and a new key, instead of retrying immediately. The error reference lists the codes. Quiet-hours and opt-out handling reduce risk, but consent and content remain the sender's responsibility.
Cost and registration
A segment costs $0.0075 plus a $0.0045 carrier fee. A card on file and a number of your own ($2 a month) are required to send. An account can send up to 500 texts a month before it registers; after that it has to, and most approvals take 2 to 7 days. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing. The pricing page has the full list.
Frequently asked questions
Does Pub/Sub guarantee a message is delivered once?
No. It guarantees at-least-once delivery by default, so design the handler to be safe when it sees a message twice. The idempotency key is how.
What should the handler return for a refused send?
A 2xx, after logging it. Returning an error would make Pub/Sub deliver the same refused request again and get the same refusal.
Can I use the same pattern for many recipients?
Yes. Publish one message per recipient, or use POST /v1/messages/bulk, which takes up to 100 recipients per call, and keep one key per batch.
The short version
Receive the push, call POST /v1/messages with a UUID the producer created, acknowledge on success and on permanent refusals, and fail only when a retry could help. For the same idea on a function platform, see sending SMS from AWS Lambda, and for a first send, the API quickstart. When you want to try it, sign up and text from your own number.