Reference

Batch send

Up to a hundred messages in one request, each reported by its index. One refused item does not take the other ninety-nine down — and the ninety-nine are durably accepted rather than rolled back alongside it.

Endpoint

POST/v1/emails/batchemails:send

Every item takes the same fields as POST /v1/emails — including template, stream, tags, attachments and idempotencyKey.

Status	When
`202`	At least one item was accepted.
`422`	Nothing was accepted. The per-item detail still comes back — you need to know which and why.
`400`	The batch itself was invalid, and nothing was written.

Partial success is the contract

Read data by index; the order matches your request. An item is accepted, duplicate (an idempotency replay — a success that created nothing) or rejected, and a rejection carries the same error shape a single send would have returned.

Each item is committed on its own. That is a deliberate cost: it is more round trips than wrapping the batch in one transaction, and it is the only honest way to say “ninety-nine accepted”. It also stops a batch holding your account’s usage counter for its whole duration and blocking every other send you make.

Limits, checked before anything is written

Limit	Value
Messages per batch	100
Recipients after expansion	500

An item may name several recipients, so a hundred items of fifty would be five thousand messages behind one request. Both caps are checked up front — a partial send followed by a 400 is the worst of both outcomes.

Retrying

Give every item an idempotencyKey before you retry a batch. Without one, repeating the request sends everything a second time. With one, a repeat comes back as duplicate and creates nothing.

If the request fails outright with a 5xx, items already committed stay committed — retry with the same keys and you will get them back as duplicates rather than as second copies.

Examples

POST /v1/emails/batch
{
  "messages": [
    { "from": "…", "to": "[email protected]", "subject": "Hi", "text": "…",
      "idempotencyKey": "welcome-a" },
    { "from": "…", "to": "[email protected]", "subject": "Hi", "text": "…",
      "idempotencyKey": "welcome-b" }
  ]
}

NextMessage streams →Separate transactional mail from everything else, so a newsletter complaint never withholds a password reset.