Send Batch

Queue up to 100 emails in a single request

POST/v1/send/emails/batch

Validate and queue up to 100 independent emails. Each email succeeds or fails on its own; the response reports a result per item in the same order.

Requires:send:write

Use batch when you have many distinct emails to send at once, for example one receipt per customer after a nightly job. Each item has its own from, to, subject, body, and so on. Batch is not a way to send one transactional email to many recipients; for that, put the recipients in a single email's to (or bcc). It is, however, the way to send marketing mail to many people: an email with unsubscribe support must have exactly one recipient, so send one item per person.

Batch counts as one request against the per-minute rate limit but each queued email counts toward your monthly limit.

Request body

Body parameters

emailsobject[]required

1 to 100 email objects. Each accepts exactly the same fields as Send Email, including templateId, attachments, tags, and metadata.

Unknown top-level fields, and unknown fields inside any item, are rejected with 400 validation_error.

Example

Send a batch

curl -X POST https://api.do.dev/v1/send/emails/batch \
-H "Authorization: Bearer $SEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "emails": [
    {
      "from": { "email": "receipts@mail.example.com", "name": "Example Store" },
      "to": ["a@example.net"],
      "subject": "Receipt #1001",
      "text": "Thanks for your order."
    },
    {
      "from": { "email": "receipts@mail.example.com", "name": "Example Store" },
      "to": ["not-an-address"],
      "subject": "Receipt #1002",
      "text": "Thanks for your order."
    }
  ]
}'

Response202

{
"results": [
  { "id": "msg_3f9c2a1d7b8e4c0f9a1b2", "status": "queued" },
  {
    "error": {
      "code": "validation_error",
      "message": "Validation failed",
      "details": [{ "field": "to", "message": "Invalid email in 'to' field: not-an-address" }]
    }
  }
]
}

Response

The response is 202 whenever the batch itself was accepted, even if every item failed. results has one entry per input item, in input order:

Shape	Meaning
`{ "id": "msg_…", "status": "queued" }`	The email was queued.
`{ "error": { "code", "message", "details?" } }`	The email was not queued. This is the same error envelope used everywhere else; `code` is most often `validation_error`, `sender_not_verified`, or `recipient_unsubscribed`.

Items are independent: a failed item never prevents the others from being queued.

Whole-batch errors

Some conditions apply to the account rather than to an item, and reject the entire request with the standard envelope:

{
"error": {
  "code": "validation_error",
  "message": "Maximum batch size is 100 emails"
}
}

The monthly and probation checks are applied to the batch as a whole: if queuing every item would cross the limit, the entire batch is rejected and nothing is queued, so you never get a partially sent batch because of quota.