Batch.

Authentication

Use an API key with email:send. A batch consumes one request from the key’s rate limit, but every accepted, non-suppressed recipient counts toward the organization’s allowance.

Request body

Send a JSON array, not an object containing a Messages field. Each entry uses the single-send fields. The example sends two separate messages to ada@example.com, with different subjects and bodies.

The array can contain at most 500 messages. The API accepts an empty array and returns an empty array. A non-array returns ErrorCode 300; more than 500 entries returns 410.

Each message must fit the 50-recipient and 10 MiB message limits. The API permits a batch HTTP body up to 50 MiB; the managed stack’s outer proxy currently caps a request at 32 MB. Keep encoded batches below that outer cap, or split them further.

Response order

The response is an array with one result per input message, in the same order. A valid batch envelope returns HTTP 200 even when individual messages fail. Read every ErrorCode; do not use the HTTP status alone to decide which messages were accepted.

This example shows one accepted message and one refused message:

[
  {
    "To": "ada@example.com",
    "SubmittedAt": "2026-10-11T11:18:00.377Z",
    "MessageID": "d0706314-5a78-4583-a3f7-121dbf982b56",
    "ErrorCode": 0,
    "Message": "OK"
  },
  {
    "ErrorCode": 300,
    "Message": "Provide a TextBody, an HtmlBody, or both."
  }
]

Allowances and retries

Messages are checked sequentially, not as one transaction. Earlier messages can consume the remaining allowance, causing later entries to return 405. A refused message does not undo earlier accepted messages.

Retry only entries you know were refused, after fixing their cause. Replaying the whole batch can duplicate the messages already accepted. After a network timeout, inspect activity before resubmitting.