Batch sending

POST /v1/email/batch accepts up to 100 messages in one call, each with the same shape as a single send. One API request, one quota round, one idempotency key.

{
  "messages": [
    {
      "from": "you@yourdomain.com",
      "to": ["ada@lovelace.io"],
      "subject": "Your receipt #4021",
      "html_body": "<h1>Thanks!</h1>"
    },
    {
      "from": "you@yourdomain.com",
      "to": ["grace@example.com"],
      "subject": "Your receipt #4022",
      "html_body": "<h1>Thanks!</h1>"
    }
  ]
}

Per-message resultsCopy Anchor Link

Results come back per message in data, so one invalid recipient never fails the rest of the batch. Each item has the same SendResult shape as a single send:

{
  "data": [
    { "message_id": "msg_2h8Kd0Rk9Qa", "status": "queued" },
    { "message_id": "msg_5t1Lm2Np3Qb", "status": "suppressed" }
  ]
}

QuotaCopy Anchor Link

A batch of N consumes N quota units — batching is an efficiency win, not a quota loophole. empty_batch and batch_too_large are returned for empty or oversized payloads (422).

Safe retriesCopy Anchor Link

Batch sends accept Idempotency-Key too. Retry a timed-out batch with the same key and you get the original per-message results back without re-sending or re-consuming quota — the right pattern for at-least-once producers like Queues.

curl https://api.emitd.com/v1/email/batch \
  -H "Authorization: Bearer $EMITD_API_KEY" \
  -H "Idempotency-Key: nightly-receipts-2026-10-07" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [ ... ] }'