Mail API reference

Mail API · Emails

post/v1/workspaces/{workspace_id}/emails/batchAuth

Send up to 100 emails in one request

Each row is a `POST /emails` body plus an optional `idempotency_key`, processed independently: the response reports `accepted` (with the email `id`) or `rejected` (with `error.code`) per row. An `Idempotency-Key` header covers the whole request; a row `idempotency_key` covers one row, in the same dedupe namespace (so the header must differ from every row key).

Path parameters

workspace_id*string · uuid

Id of the workspace.

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

emails*array

Up to 100 emails, each processed independently: partial success is allowed and every row reports its own `accepted` / `rejected` status.

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}/emails/batch
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "emails": [
    {
      "from": "Acme <hello@mail.acme.com>",
      "to": [
        "success@simulator.amazonses.com"
      ],
      "cc": [
        "finance@example.com"
      ],
      "bcc": [
        "audit@example.com"
      ],
      "reply_to": "support@acme.com",
      "subject": "Your order has shipped",
      "html": "<p>Your order has shipped.</p>",
      "text": "Your order has shipped.",
      "template": {},
      "headers": {
        "x-entity-ref-id": "order-1234"
      },
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ],
      "idempotency_key": "order-1234-shipped"
    }
  ]
}

Response

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