Batch sending
POST /v1/send/batch
Required scope: send:write
A batch is a list of independent messages, each with its own sender,
recipients and body. It is not a multi-recipient send: that is
to, cc and bcc on a single call, and it produces
one message, not many.
Reach for a batch when each recipient needs something different, which is also the only way to personalise per recipient.
Request
{
"messages": [
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"subject": "Order 12345 confirmed",
"text": "Thanks, Alice."
},
{
"from": "receipts@yourcompany.com",
"to": ["bob@example.com"],
"subject": "Order 12346 confirmed",
"text": "Thanks, Bob."
}
]
}
Each entry takes every field POST /v1/send takes, including
template_id, variables, send_at, attachments and headers. The two
messages in a batch need not resemble each other at all.
| Maximum messages | 500 per batch |
| Minimum | 1. An empty messages array is 400 Empty batch |
| Recipients | the 100 cap applies per message, not per batch |
Idempotency
One Idempotency-Key header covers the whole batch. Per-message keys are
derived from it as <key>:<index>, so retrying a whole batch is safe: the
messages that already went are replayed from cache, and only the ones that did
not are sent.
Because keys are positional, keep your ordering stable on a retry. Reorder
the array and <key>:0 now refers to a different message, which defeats the
deduplication.
Response: partial success is the normal case
A batch returns 200, not 202, and the body reports each message
separately. A bad message fails only its own slot:
{
"data": [
{
"index": 0,
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"message_id": "<d290f1ee-6c54-4b01-90e6-d701748f0851@lockally.com>",
"status": "queued"
},
{
"index": 1,
"error": "\"not-an-address\" is not a valid email address."
}
]
}
| Field | Present when |
|---|---|
index |
always. The position in your request array, so you can correlate |
id |
the message was accepted. This is the id to store |
message_id |
the message was accepted |
status |
the message was processed without error. queued, scheduled, delivered (test key) or suppressed |
error |
the message was not accepted. A human-readable reason |
Entries come back in request order, but correlate on index rather than on
array position.
Whole-batch rejections
Three things fail the entire call with a 4xx and no data at all:
400 Missing Idempotency-Key |
the header is required |
400 Empty batch |
messages was absent or empty |
400 Batch too large |
more than 500 messages |
Rate limits and allowance are applied per message, not per batch, so a batch
can partially succeed and then start returning quota errors in later entries
once you cross a cap. Those appear as error strings on the affected slots.
Choosing a batch size
500 is the ceiling, not a recommendation. Each message is validated and enqueued in turn within a single request, so a very large batch holds the connection open for correspondingly longer. Batches in the low hundreds are a reasonable default, and smaller ones give you more useful retry granularity.