Send one template to many recipients

POST https://api.dairo.app/v1/letters/batches

Fans one stored template out to up to 1,000 recipients, creating one letter per recipient rendered with that recipient's templateData. The whole request is validated up front — one malformed address, an unsupported to.country, or an unknown templateId (404) rejects the batch with nothing created. from, print, delivery, paymentSlip, autoSend, notifications, and metadata are shared by every member letter; only the address and templateData vary per recipient. Returns { id, total, status: "queued" } immediately, then rendering, printing, and posting proceed asynchronously — each member follows the normal lifecycle and emits letter.status_changed webhook events carrying its batchId. Each letter is priced and billed individually; list the members with GET /v1/letters?batchId=... and watch the rollup on GET /v1/letters/batches/{id}. Requires the letters:send scope.

Scope: letters:send. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/letters/batches" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "recipients": [
      {
        "to": {
          "name": "Ada Lovelace",
          "company": "Acme GmbH",
          "street": "Hauptstraße",
          "houseNumber": "1",
          "poBox": null,
          "addressLine2": null,
          "postalCode": "10115",
          "city": "Berlin",
          "country": "DE"
        },
        "templateData": {}
      }
    ]
  }'

Body

Required, application/json: CreateLetterBatchRequest.

Response

200 Success. Body: application/json, LetterBatchCreateResponse.

{
  "object": "letter_batch",
  "id": "string",
  "total": 0,
  "status": "string"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.