• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

API3 min read

Batch sending: how partial rejections work

One bad number should not sink a batch of a thousand. How the batch endpoint validates each message, what the response contains and how to handle rejections.

SMSMeteor API teamPublished 21 September 2026, updated

Real contact lists are never clean. A batch of a thousand numbers almost always contains a typo, a landline or a destination nobody can route. An all-or-nothing batch endpoint turns each of those into a failed request and a retry loop on the client side. The SMSMeteor batch endpoint works differently: it accepts what it can send and tells you, item by item, what it refused and why.

The contract

POST /v1/messages/batch takes up to 1,000 messages per API request, each with its own to and text and an optional from and reference. Top-level fields such as from, campaign, send_at, window and pace apply to every message that does not override them. Two levels of validation follow:

  • If the request itself is malformed, for example invalid JSON or more items than allowed, the whole request is refused with an error and nothing is queued.
  • If the request is valid but some messages are not, those messages are returned as rejected with their error, and every valid message is queued.

What the response contains

The response reports how many messages were accepted and rejected, the total price of the accepted ones, and the list of messages with their status:

JSON
{
  "batch_id": "bat_3Hq9Zr",
  "accepted": 2, "rejected": 1,
  "total_price": "0.0326", "currency": "USD",
  "messages": [
    { "id": "msg_9Kd2fQ", "to": "+14155550142", "status": "queued" },
    { "id": "msg_9Kd2fR", "to": "+447400123456", "status": "queued" },
    { "to": "+44 74", "status": "rejected", "error": "invalid_number" }
  ]
}

The exact fields are documented in the API reference and in the OpenAPI file.

Why items are rejected

  • The number is not a valid E.164 number for its country.
  • The destination is not one we route to.
  • The text is longer than 6 parts per message.
  • The content is refused by the filters that enforce the acceptable use policy.

Rejected messages are never billed and never reach a carrier. They are listed with the campaign in the report, so you can fix the source rather than the symptom.

Retrying without sending twice

Networks fail between your server and ours. If a batch request times out, you cannot know whether it was processed. Send every batch with an Idempotency-Key header: a retry with the same key returns the original result instead of queuing the messages a second time. Use a key that identifies the business operation, such as the campaign and the chunk number, not a random value generated on each attempt.

Throughput

The API allows 50 requests per second per key, and a batch counts as one request. Sending large lists as batches of up to 1,000 messages per API request is therefore the fastest way in, and pacing is better handled with the pace parameter, per minute or over a number of hours, than with sleeps in your own code.

Clean upstream anyway

Partial rejection is a safety net, not a list cleaner. Normalise numbers to E.164 before sending, remove duplicates, and drop numbers that came back as unknown in previous campaigns. The panel importer does this for files and reports what it removed; the guide to preparing a contact list explains each step.

Checklist for batch integrations

  1. Chunk lists into batches of at most 1,000 messages per API request.
  2. Send each chunk with a stable Idempotency-Key.
  3. Store the returned message ids with your own reference values.
  4. Log rejected items with their error and fix the source data.
  5. Use pace and window instead of client-side timing.
Send with the product this post is about.An email address opens the account. Rates are public, payment is crypto.
Start sending