Render a template proof with a sample recipient

Renders the template with a fixed sample recipient and returns the composited proof as pdfBase64 — nothing is created, printed, or billed.

Endpoint

POST https://api.dairo.app/v1/letters/templates/{id}/preview

Renders the template with a fixed sample recipient and returns the composited proof as pdfBase64 — nothing is created, printed, or billed. Pass templateData to fill the {{placeholder}} variables and addressPlacement (left, the default, or right; any other value is a 400) to check either window position. Use the proof to verify layout and page count before fanning the template out with POST /v1/letters/batches. Requires the letters:send scope.

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/3fa85f64-5717-4562-b3fc-2c963f66afa6/preview" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`id`	string	yes	The letter template's ID.

Body

Optional, application/json: PreviewLetterTemplateRequest.

All fields optional; the proof renders with a sample recipient and, by default, left address placement.

Field	Type	Required	Description
`templateData`	object	no	Values that fill the template's {{placeholders}} for the preview.
`addressPlacement`	LetterAddressPlacement	no
`output`	`"inline"`, `"url"`	no	`inline` (default): the PDF as `pdfBase64`. `url`: the PDF is stored and a 15-minute `pdfUrl` is returned with `pageCount`, `pageSize`, `valid`, `summary`, `failedChecks` and `checks` from the layout check, and no base64. (default `"inline"`)

Response

200 Success. Body: application/json, LetterTemplatePreview.

Field	Type	Required	Description
`object`	`"letter_template_preview"`	yes
`templateId`	string	yes
`addressPlacement`	LetterAddressPlacement	yes
`pdfBase64`	string	no	The rendered PDF, base64. Present only for `output: inline`.
`pdfUrl`	string (uri) or null	no	`output: url` only: a presigned download URL for the PDF (null when storage is unavailable).
`pdfUrlExpiresInSeconds`	integer or null	no	`output: url` only: seconds until `pdfUrl` expires (900).
`pageCount`	integer	no	`output: url` only.
`pageSize`	object or null	no	`output: url` only: the rendered page size from the layout check.
`valid`	boolean or null	no	`output: url` only: the layout-check verdict (null when the check was unavailable).
`summary`	any	no	`output: url` only: the layout-check summary (null when unavailable).
`failedChecks`	array of string	no	`output: url` only: ids of the layout checks that failed (empty when none failed or the check was unavailable).
`checks`	array of object	no	`output: url` only: every layout check as `{id, status, message}`, the same list `POST /v1/letters/verify` returns without the `expected`/`actual` detail.
`sizeBytes`	integer	no	`output: url` only: PDF size in bytes.
`agentHint`	string	no	`output: url` only, when storage was unavailable.

200

{
  "object": "letter_template_preview",
  "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "addressPlacement": "left",
  "pdfBase64": "string",
  "pdfUrl": "https://example.com",
  "pdfUrlExpiresInSeconds": null,
  "pageCount": 0,
  "pageSize": {},
  "valid": true,
  "summary": "string",
  "failedChecks": [
    "string"
  ],
  "checks": [
    {
      "id": "string",
      "status": "pass",
      "message": "string"
    }
  ],
  "sizeBytes": 0,
  "agentHint": "string"
}

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`).