Send a batch of transactional emails

Sends up to 100 messages in one call, each with its own recipient, template or inline body, and variables. Use it to cut request volume when something in your system produces many receipts or alerts at once. For marketing, use a broadcast instead.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token: Authorization: Bearer sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

X-API-Key<token>

API key via header: X-API-Key: sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

Request Body

application/jsonRequired

bodyRequiredarray<object>

A JSON array of messages, each in exactly the shape a single send takes. Different recipients, templates, subjects and variables per item are all fine. At most 100 per call.

curl -X POST "https://clientsphere.io/api/v1/transactional/batch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "to": "ada@example.com",
      "templateSlug": "order-receipt",
      "variables": {
        "firstName": "Ada",
        "orderId": "A-1041"
      },
      "idempotencyKey": "order-A-1041-receipt"
    },
    {
      "to": "grace@example.com",
      "templateSlug": "order-receipt",
      "variables": {
        "firstName": "Grace",
        "orderId": "A-1042"
      },
      "idempotencyKey": "order-A-1042-receipt"
    }
  ]'

The batch was processed. data holds one entry per item in request order — a message where the send was accepted, an error where it was not. The batch is not atomic: an email that has left cannot be recalled, so one item failing never rolls the others back. Read meta.failed rather than assuming success from the status code.

{
  "data": [
    {
      "index": 0,
      "id": "6f1c0d3e-2a4b-4c1d-9e8f-0a1b2c3d4e5f",
      "status": "sent",
      "to": "ada@example.com",
      "subject": "Your receipt A-1041",
      "templateSlug": "order-receipt",
      "idempotencyKey": "order-A-1041-receipt",
      "batchId": "c4d7e8f9-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "createdAt": "2026-09-07T10:12:03.418Z",
      "sentAt": "2026-09-07T10:12:03.902Z"
    },
    {
      "index": 1,
      "error": {
        "code": "INVALID_VARIABLES",
        "message": "Missing required variables: orderId.",
        "details": [
          {
            "missing": [
              "orderId"
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "batchId": "c4d7e8f9-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "total": 2,
    "sent": 1,
    "queued": 0,
    "failed": 1
  }
}

Send a batch of transactional emails

Authorization

Request Body

Response

TypeScript