Create a reusable letter template

Stores a reusable letter design: html carries the body and branding, with {{placeholder}} variables filled per letter at send time.

Endpoint

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

Stores a reusable letter design: html carries the body and branding, with {{placeholder}} variables filled per letter at send time. A template never contains a recipient — Dairo composites the recipient from each letter's to address into the envelope window when the letter is rendered, so leave that area blank. html may be at most 512 KiB (a larger body is a 413); variables optionally declares the placeholders (a JSON array or object, 16 KB max); status is active or archived and defaults to active. Requires the letters:send scope. Render a proof with POST /v1/letters/templates/{id}/preview before sending.

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

Request

cURL

curl -X POST "https://api.dairo.app/v1/letters/templates" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "html": "string"
  }'

Body

Required, application/json: CreateLetterTemplateRequest.

Field	Type	Required	Description
`name`	string	yes
`html`	string	yes	The branded letter HTML. Use {{placeholders}} where values vary per recipient and leave the recipient address window blank.
`variables`	array of string or LetterTemplateVariable or object	no	Declared template variables. Preferred: [{name, type?, example?, label?}]. Also accepted: an array of names, or an object {name: type}. Stored and returned in the preferred shape.
`status`	LetterTemplateStatus	no

Response

200 Success. Body: application/json, LetterTemplate.

Field	Type	Required	Description
`object`	`"letter_template"`	yes
`id`	string	yes
`name`	string	yes
`html`	string	no	The branded letter HTML with {{placeholders}} and a blank recipient address window. Omitted from list items.
`variables`	array of LetterTemplateVariable	no	Declared template variables, stored and returned as [{name, type?, example?, label?}].
`status`	LetterTemplateStatus	yes
`createdAt`	string (date-time) or null	no
`updatedAt`	string (date-time) or null	no

200

{
  "object": "letter_template",
  "id": "string",
  "name": "Ada Lovelace",
  "html": "string",
  "variables": [
    {
      "name": "Ada Lovelace",
      "type": "string",
      "example": "string",
      "label": "production"
    }
  ],
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "updatedAt": "2026-10-19T09:30:00Z"
}

Errors

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

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).

Create a reusable letter template

Request

Body

Response

Errors

On this page