POST /v1/emails/batch when one job already contains several independent email requests.
A batch reduces HTTP overhead; it does not turn the items into one shared email.
Request shape
Send an object with anitems array.
Each item uses the normal send-email fields and may have its own recipient, sender, subject, content, schedule, tags, metadata, tracking settings, and idempotency key.
Limits and acceptance
- A request contains at most 100 items.
- The key needs
emails:send. - The batch endpoint currently allows 30 requests per 60 seconds per API key.
- Signal validates and queues the batch atomically: either every item is accepted or none is queued.
- After acceptance, each message delivers independently and can reach a different terminal status.
Correlate results
The response returnsresults in input order.
Each result includes its zero-based index and, when accepted, message identifiers and initial state.
Persist the mapping between your job item and the returned Signal ID.
Retry safely
Give every item its own project-scopedidempotencyKey.
If the caller loses the response, submit the same logical items with the same keys.
Do not generate a new key for each retry because that creates new sends.
When not to batch
Use individual sends when each message is produced by a separate job, when failures need independent HTTP retry timing, or when your queue already controls concurrency. Use a topic or segment audience send when the intent is one audience operation rather than a collection of unrelated transactional messages.SDK example
After creating an authenticated client with the matching SDK setup guide, use the operation for your language or framework. Builditems from normal send requests, then submit the collection in one call.
TypeScript