templateId and a recipient, and Dairo renders the letter, fills the
placeholders, and places the recipient in the envelope’s address window.
Templates use the letters scopes. Reading templates needs
letters:read;
creating, updating, and previewing them — and sending letters from them —
needs letters:send.How a template renders
Design the template with its recipient address area empty — that is the one rule. Dairo owns the address window: theto address you pass at send time is
composited into the window, aligned to the addressPlacement you chose, so
one template serves every recipient. A from sender on the send call adds a
return-address line at the top of the window.
Inside the HTML, write {{placeholders}} wherever a value changes per letter —
a name, an amount, a due date. At render time each placeholder is replaced by
the matching templateData value, HTML-escaped so a value can never inject
markup. A placeholder with no matching value renders as empty text — preview
the template to catch typos before anything is printed.
Create a template
POST /v1/letters/templates stores a template. Give it a name and the
letter as html. Optionally declare the placeholder names in variables (a
JSON array or object, up to 16 KB) as machine-readable documentation for
whoever — or whatever agent — fills them later.
letter_template with its ltpl_… id — from then on your
sending code carries the id, never the document.
Preview before you send
POST /v1/letters/templates/{id}/preview renders a proof with a built-in
sample recipient — no letter is created and nothing is printed. Pass
templateData to fill your placeholders and an optional addressPlacement
(left, the default, or right). The response carries the composited proof
as pdfBase64.
Manage templates
The list returns templates most recent first and omits each template’s
html
body; fetch one by id for the full document. An update changes any of name,
html, variables, or status — set status to archived to retire a
template without deleting it, and back to active to restore it.
Send a templated letter
To send one letter from a template, callPOST /v1/letters with the
templateId as the document source — in place of pdfBase64 — plus the
recipient to and the templateData that fills the placeholders. Everything
else works exactly like an inline-PDF send: same print and delivery options,
same lifecycle, same tracking.
cURL
letter object at status: "queued", tracked
like any other letter.
The template render path is also the only place Dairo can generate a payment
slip for you — pass a payment object alongside the templateId. See
Print & delivery options.
To send the same template to many recipients, a batch
renders it once per recipient — each letter with its own templateData and
its own placed address — in a single call.
Templates vs. inline PDFs
Reach for a template whenever the same branded letter goes to more than one
recipient — dunning notices, statements, renewal letters. For a single,
already-finished document, an inline PDF send is
the shorter path.
Next steps
- Layout & verification — the zones a template must keep clear, ready-made compliant starter templates from
GET /v1/letters/requirements, andPOST /v1/letters/verifyto check a render before it mails. - Status & tracking — follow every templated letter from queued to delivered.
- Pricing — project what a templated run costs before it goes out.