Bulk send and message lookup

#Send to many

Sends one text to up to 100 recipients, with a result for each. Each recipient is billed as one send.

Bulk is synchronous: 5 recipients at a time, returning when all are done. Set a client timeout longer than 120 seconds. After a timeout, retry with the same Idempotency-Key.

Parameters

Idempotency-Keystring, headerRecommended: One key for the whole batch.
tostring[]Required: Up to 100 recipients, E.164 recommended.

More
Entries that aren’t non-empty strings are skipped and not counted in total. Duplicate numbers aren’t merged: the repeat is refused as duplicate_send. A group text is the exception: its duplicates are merged before it is counted.
bodystringRequired: The text for every recipient. message is an alias.
consent_attestedbooleanRequired: Your promise that every recipient agreed to texts from you. Not refused yet (as on /v1/messages).

More parameters

fromE.164 string: One of your numbers.
media_urlstring: Image URL, as in Send a message.
confirm_empty_mergeboolean: Send true to send even when a merge field is blank for some recipients. Without it, those recipients get empty_merge_field and are not sent.
groupboolean: Send one group text: everyone in to gets it in one shared thread.

More
Needs 2 to 10 different numbers and a from number on an approved texting campaign. No merge fields, since everyone sees the same text. Each person is billed as one MMS. Someone who opted out or is in quiet hours is left out of the group and isn’t charged. Replies come into each person’s own conversation.

Returns

Returns 200 once the batch is processed, even if every recipient failed: check data.failed and each results[].sent. With a test key, nothing is sent and each result has a test-msg-… message_id and its segments.

data.totalinteger: Recipients processed.
data.sentinteger: How many were accepted.
data.failedinteger: Every recipient not sent and not held. That includes a recipient whose result has error_code send_outcome_unknown: that text may have gone out, so check List messages before you send it again.
data.heldinteger: How many are held for quiet hours and will send on their own.
data.groupboolean: true on a group send. Missing otherwise.
data.results[]object[]: One per recipient: to, status (the HTTP status a single send would have returned), sent, and either message_id, segments and sent_body, or error and error_code. A held recipient has queue_id, queued_for, send_at, recipient_tz and warning instead.

More
A refused recipient’s error_code is what a single send returns (in error_code or code), else "send_failed", or "send_error" when the send failed on our side before anything went out (safe to retry). no_route and send_outcome_unknown mean it may have gone out: check List messages before you send it again. send_dedupe_unavailable means nothing was sent and it is safe to retry. Read error before retrying.
data.results[].heldboolean: true when the text is held for quiet hours. queue_id is the held text, recipient_tz the time zone used, and warning says why it was held: it isn’t sent yet, goes out at send_at, and must not be sent again. A held recipient has "sent": false and counts in held, not failed.

Errors

HTTP	Code	When
400	`invalid_request`	`to` isn’t a list with at least one number, or there’s no body.
400	`too_many_recipients`	More than 100 recipients.
400	`invalid_from`	Not one of your numbers.
400	`invalid_field`	`from` is a list or an object, not one number.
400	`invalid_media_url`	`media_url` isn’t one web address that starts with `http://` or `https://`. Nothing is sent.
400	`invalid_group_size`	`group` with fewer than 2 or more than 10 different numbers.
400	`group_from_required`	`group` without `from`.
400	`group_from_unregistered`	`from` isn’t on an approved texting campaign.
400	`group_merge_fields`	A group text with merge fields.
402	`insufficient_credits`	Your balance can’t cover the whole batch, so nothing is sent. Has `required_cents`, `balance_cents` and `recipients`. Top up in Billing by at least the difference, then try again.
402	`client_card_required`	A sub-account that pays with its own card and has not added one yet. Add one in Billing.
409	`idempotency_in_progress`	Same key while the batch still runs.
429	`throughput_exceeded`	The batch is over your carrier throughput, so nothing is sent. Has `retry_after_ms` and `cap_per_sec`.
429	`rate_limited`	Over the per-account limits.

curl -X POST "https://api.tryready.com/v1/messages/bulk" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      "+12125550199",
      "+15559876543"
    ],
    "body": "We are open late tonight until 9.",
    "consent_attested": true
  }'

const res = await fetch('https://api.tryready.com/v1/messages/bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "to": [
      "+12125550199",
      "+15559876543"
    ],
    "body": "We are open late tonight until 9.",
    "consent_attested": true
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/messages/bulk",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "to": ["+12125550199", "+15559876543"],
        "body": "We are open late tonight until 9.",
        "consent_attested": True
    },
    timeout=125,  # 5 s past the request deadline
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "total": 2,
    "sent": 1,
    "held": 0,
    "failed": 1,
    "results": [
      {
        "to": "+12125550199",
        "status": 200,
        "sent": true,
        "message_id": "179088672338905475132359",
        "segments": 1,
        "sent_body": "Your order #1042 has shipped. Reply STOP to opt out. -Acme Co"
      },
      {
        "to": "+15559876543",
        "status": 403,
        "sent": false,
        "error": "This contact replied STOP and is opted out. They must reply START from their phone to opt back in.",
        "error_code": "opt_out_locked"
      }
    ]
  }
}

#Get a message

One message your account sent or received, including texts your team members sent. Returns a Message object in data.

Parameters

idstring, pathRequired: The message_id a send returned.

Errors

HTTP	Code	When
404	`message_not_found`	No such message on your account (or it’s another account’s).
429	`rate_limited`	Over the per-account limit.
503	`message_reference_ambiguous`	The id matches more than one message. Contact support before you send it again.

curl "https://api.tryready.com/v1/messages/179088672338905475132359" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/messages/179088672338905475132359', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/messages/179088672338905475132359",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "message_id": "179088672338905475132359",
    "status": "delivered",
    "error_reason": null,
    "error_detail": null,
    "blocked": false,
    "from": "+14155550100",
    "to": "+12125550199",
    "body": "Your order #1042 has shipped.",
    "sent_body": "Your order #1042 has shipped. Reply STOP to opt out. -Acme Co",
    "media_url": null,
    "segments": 1,
    "created_at": "2026-10-01T20:32:03.473Z",
    "sent_at": "2026-10-01T20:32:04.102Z",
    "delivered_at": "2026-10-01T20:32:09.856Z",
    "reply_category": null
  }
}

{
  "success": true,
  "data": {
    "message_id": "179088672338905475132360",
    "status": "failed",
    "error_reason": "recipient_cannot_receive_sms",
    "error_detail": "Recipient's number can't receive texts. Try calling instead.",
    "blocked": false,
    "from": "+14155550100",
    "to": "+15559876543",
    "body": "Your order #1043 has shipped.",
    "sent_body": "Your order #1043 has shipped.",
    "media_url": null,
    "segments": 1,
    "created_at": "2026-10-01T20:33:10.215Z",
    "sent_at": "2026-10-01T20:33:10.990Z",
    "delivered_at": null,
    "reply_category": null
  }
}

Older paths

These paths predate /v1. They keep working and we aren’t turning them off; new code should use the /v1 endpoints. With an API key, the two GETs answer with a Deprecation: true header and a Link header (rel="successor-version") to the /v1 docs; the body doesn’t change.

POST /sms/send: the same send as POST /v1/messages. It stays for existing callers; new code should use POST /v1/messages. The text goes in message (body is an alias; message wins if you send both), and it also takes from_phone_number_id, which overrides from_strategy. A missing to answers 400 with error_code: "missing_field".
GET /sms/logs: the dashboard’s raw message log (50 rows a page by default; its search covers only your most recent 10,000 messages). Use GET /v1/messages. hasMore becomes has_more, offset becomes before_id (pass back next_before_id), a row on /v1 has the same value in both id and message_id, and status uses the public words (queued, not sent or pending).
GET /phone-numbers: use GET /v1/numbers.