Batch sends and scheduled sends

01One hundred per request

POST /v1/emails/batch takes an array of up to a hundred message objects — each one exactly the same shape you would send to /v1/emails on its own — and accepts them as a hundred separate messages.

POST /v1/emails/batch
[
  { "from": "Acme <[email protected]>", "to": ["[email protected]"],
    "subject": "Invoice 4821",   "html": "<p>Due 30 Sep.</p>" },
  { "from": "Acme <[email protected]>", "to": ["[email protected]"],
    "subject": "Invoice 4822",   "html": "<p>Due 30 Sep.</p>" }
]  // … up to 100 items

The hundred is not a tier and there is no plan that raises it. A batch is one atomic unit of work with one request timeout, and an unbounded array cannot be given a sensible one — the honest choices are a fixed ceiling or a request that sometimes dies half-processed with no way to find out what happened. Above a hundred, split into multiple requests; the endpoint is cheap and the messages are independent anyway.

02One bad item does not fail the batch

The response is { "data": [ … ] }, one entry per item, in the order you sent them. Nothing about a bad item at position seven touches the other ninety-nine.

$ curl -s -X POST … /v1/emails/batch -d @invoices.json
{ "data": [
  { "id": "email_2Nq8x…" },
  { "id": "email_2Nq8y…" },
  { "index": 2, "error": { "name": "invalid_to_address",
                          "message": "`bob@@example.com` is not a valid address." } },
  { "id": "email_2Nq8z…" }
] }
# 3 accepted, 1 rejected, HTTP 200 for all of it

The alternative design — reject the whole batch on the first bad item — sounds safer and is worse in practice. It forces the caller to diff two arrays to work out what happened, it turns one typo in a CSV import into ninety-nine messages that never went, and it produces a retry loop that resends the ninety-nine good ones every time while never fixing the one that is broken.

03Scheduling a send

Add scheduled_at to any send — single or batched — and the message is stored with status scheduled instead of being queued immediately. You get the same response shape and the same id; the only difference is when the send path picks it up.

04Rescheduling and cancelling

Two operations, one precondition. PATCH /v1/emails/:id with a new scheduled_at moves a message; DELETE /v1/emails/:id cancels it. Both require the message to still be in the scheduled state, and both return a not-found error otherwise.

$ curl -X PATCH … /v1/emails/email_2Nq8x -d '{"scheduled_at":"in 6h"}'
{ "object": "email", "id": "email_2Nq8x", "scheduled_at": "2026-09-11T15:31:04.118Z" }

$ curl -X DELETE … /v1/emails/email_2Nq8x
{ "object": "email", "id": "email_2Nq8x", "status": "canceled" }

$ curl -X DELETE … /v1/emails/email_2Nq8x
404 not_found
Only a scheduled message can be canceled. This one has already been queued or sent.

The cancel is two steps and both of them matter. The database row is moved to canceled under a condition that only matches a still-scheduled row — so two concurrent cancels cannot both succeed, and a cancel racing the scheduler loses cleanly rather than half-applying — and then the timer holding that message is told to drop it. Doing only the first would leave a fired timer looking for a message that is no longer sendable; doing only the second would leave a row claiming it is still going out.

05When to use a broadcast instead

They are not two sizes of the same feature, and the difference shows up in how each one behaves when it gets big.

A broadcast is split into thirty-two fixed ranges, each with its own coordinator and a monotonic cursor, and there is deliberately no counting pass anywhere in it. A count is a full scan that returns a number which is stale the instant it is computed, and it gets slower in exact proportion to how expensive it already was. Because progress is a cursor rather than a count, pausing and resuming is the same operation the system already performs after a crash — which is why it is trustworthy, rather than a feature bolted on beside the happy path.

So: clumps of transactional mail are batch work — a nightly run of invoices, a queue of receipts, fifty password resets from an incident. Anything where the recipient list is a query rather than a list, and where you would want to stop it halfway and look, is a broadcast.

Common questions