Mail API reference

Mail API · Templates

post/v1/workspaces/{workspace_id}/templates/{name}/send-batchAuth

Send up to 100 messages with the same template in one request. Per-row partial-success: each row carries its own status (`accepted` | `rejected`).

Two ways to make retries safe. An `Idempotency-Key` header covers the whole request: a retry with the same key and body within 24 h returns the first response (with `Idempotent-Replay: true`) and sends nothing. A per-row `idempotency_key` covers one message: a later batch, or a `/send`, that repeats a row key replays that row instead of sending it again. Both share one dedupe namespace, so the header key must differ from every row key (400 otherwise).

Path parameters

workspace_id*string · uuid

Id of the workspace.

name*string

Name of the template.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

messages*array

Up to 100 messages to render and enqueue in a single call. Each is processed independently — partial successes are allowed.

Response · 200

data*array

One status per row, in request order.

summary*object
accepted*number

Rows accepted for sending.

rejected*number

Rows rejected.

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/templates/{name}/send-batch
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "messages": [
    {
      "from": "Acme <noreply@acme.com>",
      "to": "alice@example.com",
      "cc": [
        "finance@example.com"
      ],
      "bcc": [
        "audit@example.com"
      ],
      "reply_to": "support@acme.com",
      "headers": {
        "x-entity-ref-id": "order-1234"
      },
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ],
      "subject": "string",
      "data": {
        "name": "Alice",
        "code": "A1B2C3"
      },
      "topic_id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
      "idempotency_key": "string"
    }
  ]
}

Response

{
  "data": [
    {
      "index": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "status": {},
      "error": {}
    }
  ],
  "summary": {
    "accepted": 0,
    "rejected": 0
  }
}