You can send an SMS from a Cloudflare Worker with one fetch call to POST /v1/messages, no SDK and no Node APIs. Store the API key as a Worker secret, send it in the X-API-Key header, and add an Idempotency-Key header so a retry never texts the same person twice.
Workers suit this job well: they start fast, sit close to the request, and fetch is the whole HTTP client. The catch is that a Worker can be asked to do the same work twice (a client retry, a queue redelivery, your own retry loop), and a text is the one side effect you can't take back. This post shows a working handler, where waitUntil helps and where it doesn't, and how to retry without duplicates.
The minimal Worker
The request shape is the same everywhere: base URL https://api.tryready.com, JSON body, to in E.164 (a 10-digit US number is treated as +1), and consent_attested set 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.
export default {
async fetch(request, env, ctx) {
const { messageId, phone, orderId } = await request.json();
const message = {
to: phone,
body: `Your order #${orderId} has shipped.`,
consent_attested: true,
};
ctx.waitUntil(sendText(env, message, messageId));
return new Response("accepted", { status: 202 });
},
}; The caller supplies messageId, a UUID created once when the order event was first recorded. That detail matters more than it looks, and we come back to it below.
Keep the key in a secret
Never put the API key in wrangler.toml or in source. Add it with wrangler secret put READY_API_KEY for production, and use a local .dev.vars file (kept out of git) for development. Inside the Worker it shows up on env.READY_API_KEY.
Two habits keep it safe:
- Log the idempotency key and the HTTP status, never the headers.
- Use one key per environment, so a leaked staging key can't send from production.
Our post on API key security and rotation covers rotation without downtime.
The send function with retries
Here is the function that waitUntil runs. It retries only the failures a retry can fix: network errors, timeouts, 429 and 5xx. Every attempt reuses the same Idempotency-Key, so if the first attempt reached Ready but the response was lost, the second one doesn't send again.
async function sendText(env, message, idempotencyKey) {
for (let attempt = 1; attempt <= 3; attempt++) {
try {
const res = await fetch("https://api.tryready.com/v1/messages", {
method: "POST",
headers: {
"X-API-Key": env.READY_API_KEY,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(message),
signal: AbortSignal.timeout(8000),
});
if (res.ok) return true;
const retryable = res.status === 429 || res.status >= 500;
if (!retryable) {
console.error("send refused", res.status, idempotencyKey, await res.text());
return false;
}
} catch (err) {
// network error or timeout: fall through and retry with the same key
}
await new Promise((r) => setTimeout(r, 400 * 2 ** attempt));
}
console.error("send gave up", idempotencyKey);
return false;
} A 4xx means Ready understood the request and refused it (a bad number, a missing field, an opted-out contact), so retrying won't change the answer. The error reference at docs.tryready.com/api/errors lists the codes. For the longer treatment of when to retry and when to stop, see SMS API retries and failure handling.
What waitUntil does, and what it doesn't
ctx.waitUntil() lets the Worker answer the caller immediately while the send finishes in the background. That's the right call when the caller doesn't need to know the text went out, such as a webhook that only wants a fast 2xx.
It isn't a durable queue. If the Worker is evicted or the work runs past the platform's limits for background tasks, nothing retries it for you. So pick by how much the text matters:
| Situation | Approach |
|---|---|
| Webhook wants a fast 2xx, text is nice to have | waitUntil with the retry loop above |
| Text must go out (receipts, codes, reminders) | Put the job on a queue and send from the consumer, letting the queue redeliver |
| Caller needs the outcome | await the send and return its status |
With a queue, redelivery becomes your retry layer, and the idempotency key is what makes redelivery safe. Our guide to queue design for platforms covers throttling and dead letters.
Where the idempotency key comes from
One UUID per message, created once, reused on every retry. The mistake to avoid is generating it inside the retry path, or inside a Worker that the caller might invoke twice, because each call would mint a fresh key and defeat the protection.
Good sources:
- A UUID stored on the order or event row when it's first written.
- A UUID the upstream service puts on the job before it's queued.
- For a Worker called by a third party that retries, a key you derive once and store (in KV or a database) against that third party's event ID.
For more on why a key beats ad hoc dedupe, read idempotency and duplicate texts.
Quiet hours, opt-outs and numbers
A few things happen on Ready's side that your Worker should expect:
- Opted-out numbers and numbers on your Ban list are refused up front and not charged.
- 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, so send it again once the window opens. - Quiet-hours rules are risk reduction, not a guarantee. Consent and content remain the sender's responsibility.
Log these refusals rather than retrying them in a loop. Format numbers to E.164 before the call; this guide shows how.
Cost and registration
On Ready, 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 for 10DLC; after that it has to register, 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. Workers' own usage costs are small next to the text itself.
Frequently asked questions
Can a Worker send SMS without a Node SDK?
Yes. The API is plain HTTPS and JSON, and fetch is built into the Workers runtime. There's nothing to install.
Should I use waitUntil or await the send?
Use waitUntil when the caller only needs a quick acknowledgment and an occasional lost text is acceptable. Use a queue or await when the text matters.
What happens if my retry fires after the first send actually worked?
With the same Idempotency-Key, the retry doesn't send a second text. That's the whole reason to send the header on every attempt.
The short version
Keep the key in a secret, call POST /v1/messages with fetch, create one UUID per message and reuse it on every retry, and put a queue behind anything that must not be lost. The API quickstart walks through your first send, and the messages reference lists every field. When you're ready to try it, sign up and send a test from your own number.