Send a batch of emails

POST/v1/emails/batch

Queues up to 100 messages in one request, each with the same fields as Send an email. Every message is validated first, so one invalid message rejects the whole request before anything is queued. After that each message is queued on its own: one that fails (a suppressed recipient, a quota) is reported in its own slot and never blocks the others.

Send an Idempotency-Key to make the whole batch safe to retry. Message N uses <key>:N.

Required scope: emails:send

Parameters

Name	In	Description
`Idempotency-Key`optional	header	Up to 240 printable characters.

Request body

Field	Type
`emails`required	`any[]`

Unknown fields are rejected, so a typo never silently does nothing.

Example

curl -X POST 'https://api.sendsend.email/v1/emails/batch' \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    {
      "from": "Acme <hello@mail.acme.com>",
      "to": [
        "a@example.com"
      ],
      "subject": "Hello A",
      "text": "Hi A"
    },
    {
      "from": "Acme <hello@mail.acme.com>",
      "to": [
        "b@example.com"
      ],
      "subject": "Hello B",
      "text": "Hi B"
    }
  ]
}'

Response `202`

{
  "object": "batch",
  "accepted": 1,
  "failed": 1,
  "data": [
    {
      "id": "msg_8Xk2…",
      "request_id": "req_Kd83…",
      "status": "queued",
      "created_at": "2026-10-06T15:04:05.000Z"
    },
    {
      "object": "error",
      "error": {
        "code": "recipient_suppressed",
        "message": "All recipients are suppressed"
      }
    }
  ]
}

Errors

Status	Code	When
400	`validation_error`	The request body or parameters are invalid. The message says which field.
401	`unauthorized`	The API key is missing, invalid or revoked.
403	`forbidden`	The key does not have the scope this endpoint needs.
429	`rate_limited`	Too many requests. Wait for the number of seconds in the Retry-After header.

Every error has the same shape. See Errors.