To send SMS from AWS Lambda, call the texting API over HTTPS with fetch, read the API key from a secrets store, and send an idempotency key derived from the triggering event. That last part is what keeps a retried invocation from texting the same person twice.
Serverless is a good fit for texting because sends are bursty and event-driven. It also adds failure modes a long-running server doesn't have: functions retry on their own, time out mid-request and start cold. Here's the pattern that handles them.
Keep the API key out of your code
Don't hardcode the key or bake it into the deployment package. Store it in your platform's secrets service, such as AWS Secrets Manager or Parameter Store, and read it at startup, outside the handler, so warm invocations reuse it. Give the function permission to read that one secret and nothing else. Rotation is easier when the key lives in one place, and our post on API key security and rotation covers the routine.
One idempotency key per event
Most serverless triggers deliver at least once. A queue message, a stream record or an event bus rule can invoke your function twice for the same event, and a timeout makes the platform retry on its own. Derive the key from something stable in the event, such as the event ID or the message ID, not from a fresh random value on each run:
// Node 20+ on Lambda. fetch is built in.
const API_KEY = process.env.READY_API_KEY; // loaded from your secrets store
export async function handler(event) {
const res = await fetch("https://api.tryready.com/v1/messages", {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Idempotency-Key": event.eventId, // stable per event, a UUID
"Content-Type": "application/json",
},
body: JSON.stringify({
to: event.phone, // E.164, like +12125550199
body: "Your order #1042 has shipped.",
consent_attested: true,
}),
signal: AbortSignal.timeout(8000),
});
const out = await res.json().catch(() => ({}));
// Throw (so the platform retries with the same key) on 429, 5xx and a first attempt still running.
if (res.status === 429 || res.status >= 500 || (res.status === 409 && out.code === "idempotency_in_progress")) {
throw new Error(`send failed: ${res.status}`);
}
return out; // 2xx or a final 4xx: record it and move on
} The Idempotency-Key header can be any string up to 255 characters, so the event ID works as is. A retried request with the same key never sends twice. For the full reasoning, see duplicate texts and idempotency, and for fields see the messages docs.
Timeouts and retries
The short version:
- Idempotency key stable per event.
- HTTP timeout shorter than the function timeout.
- Retry timeouts and server errors, park the rest.
- Dead-letter queue for events that keep failing.
Set the function timeout longer than your HTTP timeout. In the snippet the request gives up after 8 seconds, so the function's own timeout should be comfortably above that. Otherwise the platform kills the function while the request is in flight and you can't tell whether the text went out. With the idempotency key, that uncertainty is safe to resolve by retrying.
Decide what's retryable. Throwing on an error makes the platform retry, which is right for timeouts, a 429 and a 409 idempotency_in_progress (the first attempt is still running) and wrong for a bad number or an opt-out. For those, catch the error, record it and return normally so the event isn't replayed forever. Retrying a 503 with the same key only replays the stored error, so resend it under a new key. Park events that keep failing in a dead-letter queue. The split is covered in retries and failure handling, and error codes are listed in the errors docs.
A 1:1 or API text can also come back as a 409 QUIET_HOURS_BLOCK when the quiet-hours window is more than 6 hours away. Treat that as "send again later", not as a failure, and schedule the retry for when the window opens.
Cold starts
A cold start adds latency before your code runs, but it shouldn't change your design. Don't block a user-facing request on the send. Accept the request, put the text on a queue, and let a function send it. Create your config once outside the handler. If a flow needs a code to arrive quickly, measure it in your own environment rather than assuming a number.
Receiving replies in a function
Inbound texts and delivery reports arrive as webhooks, which fit a function behind an HTTPS endpoint well. Keep the handler small: verify the request, write the payload to a queue or table, and return a 2xx fast. Do the real work in a second function. Don't assume ordering or single delivery, so make the handler idempotent too. Our posts on receiving SMS through webhooks, webhook signing and out-of-order events cover the details, and the payload format is in the API quickstart.
Consent and a test first
consent_attested is your promise the recipient agreed to texts, so only invoke the function for contacts who did. Use a test key, which simulates sends, until the flow is right. Then try one real text on a number of your own.
Next step
Wire up the snippet, force a duplicate invocation and confirm only one text goes out. If you don't have an account yet, sign up and send your first text.
Frequently asked questions
Can I call the Ready API from Lambda with fetch?
Yes. Node 18 and later include fetch, so you don't need an SDK. Send a POST to /v1/messages with the X-API-Key header.
What should the idempotency key be?
Something stable per event, so every retry of that event carries the same one. Don't use a fresh random value on each invocation.
Where do I store the API key?
In your platform's secrets service, read once outside the handler.
Will a Lambda retry text someone twice?
Not if the retry reuses the same Idempotency-Key, since a retried request with the same key never sends twice while Ready still remembers the key (the docs give the window; a replay later than that sends again).