To send a scheduled text from Kubernetes, run a CronJob whose container posts to https://api.tryready.com/v1/messages with curl. Keep the API key in a Secret, set concurrencyPolicy: Forbid so runs never overlap, and derive an idempotency key from the Job's name so a retried pod can't send the same text twice.
We make Ready, so the example uses our REST API and only the request shape we document. CronJobs are a good fit for a daily digest or a nightly reminder. They also have sharp edges: Kubernetes can start a run twice, and a failed pod gets retried. Both are the situations an idempotency key exists for.
What you need before the first request
- An API key. Ready authenticates with an
X-API-Keyheader. It goes in a Kubernetes Secret, never in the image or the manifest in Git. - A card and a number. A card on file and a number of your own are required to send. The number is $2 a month. To try the CronJob first, create a test key (Settings, Developers, Environment: Test). It simulates every send with no card, number or charge.
- Consent. Each request carries
consent_attested: true, your statement that the recipient agreed to receive texts. A CronJob has no one to ask, so make sure the list it reads is limited to people who did. - Registration. An account can send up to 500 texts a month until its 10DLC registration is approved, and most approvals take 2 to 7 days. See the 10DLC explainer.
Each segment costs $0.0075 plus a $0.0045 carrier fee, and screening is extra when switched on.
The Secret
Apply a Secret from a file that stays out of version control, or create it from your secrets manager. As a manifest it looks like this:
apiVersion: v1
kind: Secret
metadata:
name: ready-api
type: Opaque
stringData:
api-key: "paste-your-test-or-live-key-here" In a real cluster, use your platform's way of syncing secrets, such as an external secrets operator, so the key never sits in Git. Our guide to API key security and rotation covers rotation.
The CronJob
apiVersion: batch/v1
kind: CronJob
metadata:
name: daily-reminder
spec:
schedule: "0 15 * * *"
timeZone: "America/New_York"
concurrencyPolicy: Forbid
startingDeadlineSeconds: 600
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 3
jobTemplate:
spec:
backoffLimit: 3
activeDeadlineSeconds: 300
template:
spec:
restartPolicy: Never
containers:
- name: send
image: curlimages/curl:8.10.1
env:
- name: READY_API_KEY
valueFrom:
secretKeyRef:
name: ready-api
key: api-key
- name: RUN_ID
valueFrom:
fieldRef:
fieldPath: metadata.labels['job-name']
command: ["/bin/sh", "-c"]
args:
- |
KEY=$(printf %s "$RUN_ID" | sha256sum | cut -c1-32 \
| sed -E 's/(.{8})(.{4})(.{4})(.{4})(.{12})/\1-\2-\3-\4-\5/')
curl -fsS -m 20 -X POST https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d '{"to":"+12125550199","body":"Your appointment is tomorrow at 10 AM.","consent_attested":true}' The example sends one fixed text to a made-up number. A real job would fetch its recipients from your own service first, then loop, building the key from the run and the recipient.
Why each setting is there
| Setting | What it protects you from |
|---|---|
concurrencyPolicy: Forbid | A slow run overlapping the next one and texting the same people twice. |
startingDeadlineSeconds | A late catch-up run firing hours after the reminder made sense. |
backoffLimit: 3 | A transient failure ending the day's send. Pods retry. |
activeDeadlineSeconds | A hung request holding the Job open indefinitely. |
restartPolicy: Never | Containers restarting in place; failures become new pods under one Job. |
curl -m 20 | A stalled connection with no timeout of its own. |
The idempotency key, per run
The Job's name is the thing that stays the same across retries. Kubernetes builds it from the CronJob name and the scheduled time, and every pod that Job starts after a failure carries the same job-name label. The script hashes that name into a UUID-shaped string and sends it as the Idempotency-Key. If the first pod sends the text and dies before it exits cleanly, the retry pod computes the same key, and a retried request with the same key doesn't send twice.
With many recipients, add the recipient to the hash input so each message gets its own key, for example the run name plus the phone number. That keeps the key stable per message, which is the rule. The post on deterministic idempotency keys works through this, and idempotency keys and duplicate texts explains the failure it prevents.
Reading failures
curl -f makes the container exit non-zero on a 4xx or 5xx, so the Job fails and backoffLimit retries it. That's right for a timeout or a 429, where the same key is safe to send again. It isn't right for a 503: nothing was sent, but the same key replays the stored error, so the retry pods fail the same way, and a new run (a new Job name, so a new key) is what sends it. After a 500 or 504 the text may already have gone out, so check GET /v1/messages before starting that new run. Nothing here tells you a Job failed, so alert on a Failed Job instead of finding out from a customer. A 4xx isn't worth retrying either, which will fail the same way each time; read the pod log, fix the request, and let the next day's run go. For error bodies, see the error codes page and the messages API reference.
Quiet hours need a mention for a scheduled job. An API text to someone in quiet hours is held only if the window opens soon. Otherwise it isn't sent and the API answers 409 QUIET_HOURS_BLOCK. Pick a schedule inside normal hours for your recipients, and read handling the quiet hours 409 for the rest.
Next step
Apply the Secret with a test key and the CronJob with a made-up number. Trigger a run by hand with kubectl create job test-run using the CronJob as the source (the kubectl docs show the flag), read the pod log, and confirm a 2xx. Then add the card and number and swap in a live key. For the same idea outside a cluster, see sending SMS from GitHub Actions and cron.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.