To resume a large SMS job after a crash without texting anyone twice, split the recipient list into fixed chunks once, store each chunk in a table with a stable idempotency key, and mark a chunk done only after the API confirms it. On restart, the worker picks up the chunks that aren't done and resends them with the same keys.
The two halves cover each other. The checkpoint stops you redoing finished work, and the idempotency key covers the one chunk that was in flight when the process died. We make Ready, so the sketch uses our bulk endpoint, but the pattern holds for any API that accepts an idempotency key.
Why re-running the loop isn't safe
The naive job reads a list, loops over batches and posts each one. If it dies at batch 37 of 90, you have three bad options: start over and re-text 36 batches, guess where it stopped, or read the sent log and hope it's complete. The last one is close to right, but a log written after the request has a gap: the request succeeded, the process died, the log line never landed.
That gap is the whole problem. A resumable job closes it by deciding what a chunk is before sending, and by making the send itself safe to repeat.
The chunk limit
POST /v1/messages/bulk takes a to array and one body, with up to 100 recipients per call. Larger lists have to be split into batches. The bulk messages docs list the endpoint. The chunk size in your job is at or under that limit, and smaller is fine. A smaller chunk makes a failure cheaper to repeat and a checkpoint finer-grained. The rate at which text actually leaves is set by your registered campaign, not by chunk size, so a bigger chunk isn't faster. Our bulk SMS API overview covers the endpoint more broadly.
Because the endpoint sends one body to everyone, personalized text needs one send per person, with the same job-table idea applied per row.
The job and chunk tables
Create the chunks up front, in one transaction, before any send. Chunking at the start is what makes "chunk 37" mean the same people after a restart.
CREATE TABLE bulk_jobs (
id bigserial PRIMARY KEY,
tenant_id bigint NOT NULL,
body text NOT NULL,
state text NOT NULL DEFAULT 'running'
CHECK (state IN ('running', 'done', 'cancelled')),
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE bulk_chunks (
job_id bigint NOT NULL REFERENCES bulk_jobs(id),
chunk_no int NOT NULL,
recipients text[] NOT NULL,
idem_key uuid NOT NULL,
state text NOT NULL DEFAULT 'pending'
CHECK (state IN ('pending', 'in_flight', 'done', 'failed')),
attempts int NOT NULL DEFAULT 0,
updated_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (job_id, chunk_no)
); Build the chunks once, with the key derived from the job and chunk number:
import uuid
NAMESPACE = uuid.UUID("0b7d2f64-51c3-4a9e-8e0d-6c2f1a9b7d35") # fixed, generated once
CHUNK_SIZE = 100 # at or under the documented bulk limit
def create_job(db, tenant_id: int, body: str, numbers: list[str]) -> int:
ordered = sorted(set(numbers)) # stable order, no duplicates
job_id = db.execute(
"INSERT INTO bulk_jobs (tenant_id, body) VALUES (%s, %s) RETURNING id",
(tenant_id, body),
).fetchone()[0]
for n, i in enumerate(range(0, len(ordered), CHUNK_SIZE)):
chunk = ordered[i:i + CHUNK_SIZE]
key = uuid.uuid5(NAMESPACE, f"{job_id}:{n}")
db.execute(
"INSERT INTO bulk_chunks (job_id, chunk_no, recipients, idem_key) "
"VALUES (%s, %s, %s, %s)",
(job_id, n, chunk, key),
)
return job_id Sorting and de-duplicating matter for the same reason as in our bulk chunking guide: the chunk contents are frozen in the table, so they can't shift under you. Set CHUNK_SIZE from the documented limit and don't hardcode a larger number.
The worker loop
The worker claims one chunk at a time, sends it, and records the result. FOR UPDATE SKIP LOCKED lets several workers share a job without grabbing the same chunk.
import os
import requests
def claim_chunk(db, job_id: int):
return db.execute(
"UPDATE bulk_chunks SET state = 'in_flight', attempts = attempts + 1, updated_at = now() "
"WHERE (job_id, chunk_no) = ("
" SELECT job_id, chunk_no FROM bulk_chunks "
" WHERE job_id = %s AND (state = 'pending' "
" OR (state = 'in_flight' AND updated_at < now() - interval '5 minutes')) "
" ORDER BY chunk_no LIMIT 1 FOR UPDATE SKIP LOCKED) "
"RETURNING chunk_no, recipients, idem_key",
(job_id,),
).fetchone()
def run_job(db, job_id: int, body: str) -> None:
while (chunk := claim_chunk(db, job_id)):
chunk_no, recipients, key = chunk
try:
resp = requests.post(
"https://api.tryready.com/v1/messages/bulk",
json={"to": recipients, "body": body, "consent_attested": True},
headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(key)},
timeout=60,
)
except requests.RequestException:
continue # stays in_flight, reclaimed later with the same key
state = "done" if resp.ok else "failed"
db.execute(
"UPDATE bulk_chunks SET state = %s, updated_at = now() "
"WHERE job_id = %s AND chunk_no = %s",
(state, job_id, chunk_no),
) The stale in_flight clause is what recovers from a crash. A chunk stuck in flight for five minutes gets claimed again, and because the idempotency key is the same, a request that actually went through before the crash is not sent twice. The five minutes is a choice for this sketch, so set it above your request timeout.
What each failure looks like
| What happened | Chunk state after | On resume |
|---|---|---|
| Crash before the request left | in_flight | Reclaimed, sent with the same key |
| Crash after the request succeeded, before the update | in_flight | Reclaimed, same key, no second text |
| Timeout, outcome unknown | in_flight | Read GET /v1/messages first, then retry with the same key (see the retries guide) |
| 4xx for the whole chunk | failed | Fix the cause, then reset to pending |
409 QUIET_HOURS_BLOCK | failed | Not sent. Requeue as a new chunk after the window opens |
A 2xx doesn't mean all N people were texted. An opted-out number, a number on your Ban list or a known landline is refused without a charge, so read the per-recipient results as the docs describe them and record them, rather than assuming. The error reference lists the codes. Never retry a suppressed number as if it were a transient failure.
Cancelling and finishing
Check bulk_jobs.state between chunks. A cancelled job stops claiming, and chunks already in flight finish. Mark the job done when no chunk is pending or in_flight, and keep failed chunks visible, because a finished job with failed chunks needs a human.
Test it by killing the worker
Run the job against a test key, which simulates sends with no number, card or charge. Kill the process mid-chunk, restart it, and count: every chunk ends done once, and your send log shows no chunk twice. Then run the finished job again and confirm it sends nothing.
The short version
Freeze the chunks first, key each one from the job and chunk number, claim them with a lease, and mark done only after the response. The checkpoint saves work and the idempotency key protects the chunk that was in flight. Together they let a restart be boring, which is what you want from a job that texts real people.