Batch Emails

Menu

Send multiple emails in a single API request. Each email in the batch is processed independently.

Endpoint

POST /v2/emails/batch

Request Body

Authentication: Send your API key via the Authorization: Bearer <api_key> header, or pass an api_key field in the wrapped request body (see below).

The batch endpoint accepts two body shapes:

1. Wrapped object (recommended):

{
  "api_key": "tsend_...",   // optional if using Authorization header
  "emails": [ /* email objects */ ]
}

2. Bare array:

[ /* email objects */ ]
FieldTypeRequiredDescription
emailsarrayYes (in wrapped form)Array of 1–100 email objects
api_keystringNoAPI key, as an alternative to the Authorization header

Each email object follows the same schema as the Send Email endpoint, including reply_to, headers, and attachments.

Example Request

curl -X POST https://api.tosend.com/v2/emails/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "emails": [
      {
        "from": {
          "name": "Acme Inc",
          "email": "hello@acme.com"
        },
        "to": [
          { "email": "user1@example.com" },
          { "name": "Jane", "email": "jane@example.com" }
        ],
        "subject": "Welcome User 1!",
        "html": "<h1>Welcome!</h1>"
      },
      {
        "from": {
          "name": "Acme Inc",
          "email": "hello@acme.com"
        },
        "to": [
          { "email": "user2@example.com" }
        ],
        "subject": "Welcome User 2!",
        "html": "<h1>Welcome!</h1>"
      }
    ]
  }'

Success Response

{
  "results": [
    {
      "status": "success",
      "message_id": "a1b2c3d4e5f6789..."
    },
    {
      "status": "success",
      "message_id": "b2c3d4e5f6789a1..."
    }
  ]
}

The HTTP status is 200 when every email is accepted.

Partial Success Response

When some emails fail validation, the response status is 207 Multi-Status. The results array is returned in the same order as the input, and successful emails are still processed:

{
  "results": [
    {
      "status": "success",
      "message_id": "a1b2c3d4e5f6789..."
    },
    {
      "status": "error",
      "status_code": 422,
      "error_type": "validation_error",
      "message": "Domain unknown.com not found for this account"
    },
    {
      "status": "spam",
      "message": "All recipient email addresses are marked as spam / disposable.",
      "errors": {
        "to": {
          "spam": "All recipient email addresses are marked as spam / disposable."
        }
      }
    }
  ]
}

Result Statuses

StatusDescription
successEmail was accepted and queued for delivery
errorThe item was rejected: validation failed, or the sender domain was not found, not verified, or not allowed for this key. See message, and errors when present
spamAll recipients were filtered as spam/disposable

A failed item does not affect the rest of the batch; the others are still accepted and queued. errors names the field that failed, so an item rejected for a bad custom header reads:

{
  "status": "error",
  "status_code": 422,
  "error_type": "validation_error",
  "message": "Validation failed",
  "errors": {
    "headers.List-ID": "Header value must be printable US-ASCII. Encode non-ASCII text as an RFC 2047 encoded-word (e.g. \"=?UTF-8?B?…?=\")"
  }
}

Safe retries with Idempotency-Key

If a batch request times out or the connection drops, you can’t tell whether toSend accepted it. Send an Idempotency-Key header and you can retry safely:

curl -X POST https://api.tosend.com/v2/emails/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -H "Idempotency-Key: newsletter-2026-11-01-part-17" \
  -d '{ "emails": [ /* ... */ ] }'
  • Use a new key for each batch, for example a UUID or your own batch ID. A key is 1 to 255 printable ASCII characters, without spaces.
  • A retry with the same key and the same body gets the first response back, with the same message_ids and status (200 or 207), and sends nothing again. The response carries the header Idempotent-Replayed: true.
  • A retry with the same key and a different body is rejected with 422. Byte-for-byte the same body, so send exactly what you sent the first time.
  • Keys belong to your team and are kept for at least 24 hours.
  • Only a response that accepted at least one email for sending is kept. After a 401, 402, 403, 422, 429 or 5xx, or a 207 where no email was accepted, nothing was sent, and a retry with the same key is processed as a new request. If the key was already used for an accepted batch, the retry gets that batch’s response instead.
  • Two requests with the same key at the same time send the batch once, and both get the same response. If a key can’t be read back (very rare), the request gets 409 and sends nothing: retry it after a moment.
  • A replayed 207 repeats the per-item errors too. To resend only the items that failed, send them as a new batch with a new key. Resending the whole body under a new key sends the successful items again.

Idempotency-Key works on POST /v2/emails/batch only. On POST /v2/emails the header is ignored, so a retried single send can send twice.

Error Responses

Idempotency-Key Reused With a Different Body (422)

{
  "status_code": 422,
  "message": "This Idempotency-Key was already used with a different request body. Use a new key for a new batch."
}

Empty Emails Array (422)

{
  "status_code": 422,
  "message": "No emails provided"
}

A body that is neither an array nor an object with an emails array returns 422 with Request body must be an array of emails or { emails: [...] }.

Batch Size Exceeded (422)

{
  "status_code": 422,
  "message": "Maximum 100 emails per batch"
}

Billing Required (402)

The account can’t send until something is done in Billing. The message says what:

{
  "status_code": 402,
  "message": "Subscription required. Subscribe in Billing to keep sending."
}
MessageMeaning
Your free trial has ended. Subscribe in Billing to keep sending.The 30-day trial is over
Your trial credits are used up. Subscribe in Billing to keep sending.The trial’s 5,000 emails are used
Subscription required. Subscribe in Billing to keep sending.No active subscription
Payment required. Update your card in Billing to resume sending.A subscription payment failed and retries ran out

Don’t retry a 402 automatically: it won’t succeed until the account owner acts. Over SMTP the same message comes back as 550 5.7.1.

Insufficient Credits (403)

{
  "status_code": 403,
  "message": "Insufficient credit balance",
  "errors": {
    "credit_balance": "1000",
    "current_usage": "3000",
    "available": "-2000"
  }
}

Notes

  • Maximum 100 emails per batch request
  • Credit balance is checked against the sum of all valid recipients before any email is queued; if there isn’t enough credit for the whole batch, the request fails with 403
  • Each email in the batch is validated independently
  • Failed emails do not affect the processing of other emails in the batch
  • Results are returned in the same index order as the input array
  • HTTP status is 200 when all emails succeed, 207 when at least one email returned error or spam
  • The total recipient count across all emails counts toward your usage