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:
{
"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
- Chunk lists into batches of at most 1,000 messages per API request.
- Send each chunk with a stable Idempotency-Key.
- Store the returned message ids with your own
referencevalues. - Log rejected items with their error and fix the source data.
- Use
paceandwindowinstead of client-side timing.


