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 happenedChunk state afterOn resume
Crash before the request leftin_flightReclaimed, sent with the same key
Crash after the request succeeded, before the updatein_flightReclaimed, same key, no second text
Timeout, outcome unknownin_flightRead GET /v1/messages first, then retry with the same key (see the retries guide)
4xx for the whole chunkfailedFix the cause, then reset to pending
409 QUIET_HOURS_BLOCKfailedNot 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.