To send a big list through a bulk SMS endpoint, split it into batches at or under the endpoint's recipient limit, give each batch a stable idempotency key, and record each batch's outcome so a crashed job resumes instead of starting over. The hard part isn't the loop, it's what happens when you run it twice.
We make Ready, so the example uses the Ready bulk endpoint: POST /v1/messages/bulk takes a to array and one body, up to 100 recipients per call. It sends the same text to everyone, so for personalized text use one send per person instead, as in our reverse ETL guide. The overview is in the bulk SMS API post.
Chunk with a stable order
import hashlib, uuid
def batches(numbers, size):
ordered = sorted(set(numbers)) # stable order, no duplicates
for i in range(0, len(ordered), size):
yield i // size, ordered[i:i + size]
def batch_key(campaign, batch_no, batch):
digest = hashlib.sha256((campaign + "|" + ",".join(batch)).encode()).hexdigest()
return str(uuid.uuid5(uuid.NAMESPACE_URL, f"{campaign}:{batch_no}:{digest}")) Sorting matters. If the order changes between runs, batch 3 holds different people and the key no longer lines up. Including a hash of the batch's contents means that if the list changed (someone opted out in between), the batch is a new request with a new key, and doesn't replay a stale one. De-duplicating first stops one person getting two texts from the same call.
Send and record
def send_batch(campaign, batch_no, batch, body):
key = batch_key(campaign, batch_no, batch)
if ledger.done(key):
return "skipped"
res = requests.post(
"https://api.tryready.com/v1/messages/bulk",
json={"to": batch, "body": body, "consent_attested": True},
headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": key},
timeout=60,
)
ledger.record(key, res.status_code, res.text)
return res.status_code The ledger is your table, with the key as its primary key. Run the job twice and the second run skips every finished batch. Run it after a crash and it picks up where it stopped. If a request timed out and you can't tell whether it went through, retry with the same key, since a repeated key means the request isn't sent twice. After a 504, or a code ending in OUTCOME_UNKNOWN, read GET /v1/messages first. The retries guide has the table.
Partial failures
A batch can be accepted while some recipients are refused: an opted-out number, a number on your Ban list or a known landline is refused up front and not charged. Read the per-recipient results in the response as the bulk messages docs describe them, instead of treating a 2xx as "all N were texted". Don't guess field names.
| Recipient outcome | What to do |
|---|---|
| Accepted | Mark sent in your ledger |
| Opted out or banned | Mark suppressed. Don't retry, ever |
| Invalid or landline | Mark bad number and send it back to whoever collected it |
Refused for quiet hours (409 QUIET_HOURS_BLOCK) | The text is not sent, so send it again once the window opens, in a later batch |
Collect the refused numbers into a "follow-up" list, and don't put them into an immediate re-send of the whole batch. That is how a person who opted out gets a second try.
Pace and size
A larger batch isn't faster. Per-second throughput is set by the registered campaign, around 1 to 4 segments a second for a fresh standard campaign and tens for higher tiers, so batches queue behind that rate either way. A smaller batch, such as a few hundred, makes a failure cheaper to retry and the ledger easier to read. Our throughput post explains the caps, and the rate limits post covers 429s.
FAQ
What's the maximum batch size?
100 recipients per call on the bulk endpoint. Split larger lists into batches.
Should I use the bulk endpoint or a campaign?
For a one-time identical campaign from code, the bulk endpoint. For scheduling, templates and reporting, the campaign tools in the app are built for it.
How do I test a batch job?
Use a test key, which simulates every send with no card, number or charge, and run the job twice to confirm the second run skips everything.
The short version
Sort and de-duplicate, key each batch by campaign, number and contents, record every outcome, and treat per-recipient results as the truth. The bulk messages docs list the endpoint.
Cost and registration
A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.