Layout & verification

A letter is printed exactly as your PDF renders, folded into a window envelope, and the recipient address is read optically from page 1 of the PDF. That means the address must sit inside the envelope window, and a few zones must stay clear for franking and postal processing. This page is the full layout contract — and the two endpoints that make it painless:

Operation	Method & path	Scope
Get requirements	`GET /v1/letters/requirements`	`letters:read`
Verify a letter	`POST /v1/letters/verify`	`letters:read`

Building with an AI agent? Point it at GET /v1/letters/requirements first: the response carries this whole spec machine-readable, plus ready-made compliant starter templates it can store and send immediately. Over MCP the same lives on the prepare_letters tool (action: "requirements" and action: "verify"). An agent needs zero prior knowledge of postal layout standards.

The three ways to get a compliant PDF

Use a starter template (easiest). GET /v1/letters/requirements returns starterTemplates[] — compliant letter HTML with {{placeholders}}. Store one via POST /v1/letters/templates, then send with templateId + templateData + to. Dairo composites the recipient into the window for you; the layout is guaranteed.
Store your own template. Write your own HTML (brand, layout, fonts) that keeps the zones below clear, store it as a letter template, and let Dairo render + place the address.
Bring your own PDF. Generate the PDF with any toolchain (HTML-to-PDF, LaTeX, ReportLab, a word processor) following the spec below — including placing the recipient address yourself — and pass it as pdfBase64 or file.

Whichever path you take: verify before you send.

Page setup

Rule	Value
Format	A4 portrait — 210 × 297 mm, every page
Max file size	25 MB (`POST /v1/letters`), 4 MB for `/verify`
Fonts	Embed all fonts in the PDF
Encryption	None — no password protection
Address	Real text, not a scanned image (it is read from the PDF)
Template letters	Render as a single A4 page

All coordinates below are measured in mm from the top-left corner of page 1.

The address window

The recipient address must sit entirely inside one window zone:

Placement	x	y	Width	Height
`left` (default)	22 mm	60 mm	85.5 mm	25.5 mm
`right`	118 mm	60 mm	85.5 mm	25.5 mm

Format the block left-aligned at 10–12 pt regular (never bold, underlined, or on a dark background — it is machine-read) with 1.2 line-height, no blank lines, at most 6 lines, in postal order: optional small return-address line (7 pt, underlined), name, company, street + house number (one line) or PO box, postal code + city (one line), country in capitals (international mail only — no country prefix on domestic letters). Keep a 3 mm left/right and 2 mm top/bottom inset inside the window. Prefer the left window — it is the postal network’s standard machine-read field and the delivery-proven default.

Registered mail is different

On a delivery: "registered" letter the carrier prints its registered-mail label and barcode into the y = 50–67 mm band of the address field. The layout shifts:

Element	Geometry
Return-address line	y 45–50 mm band (x 20–105 mm)
Carrier label + franking	y 50–67 mm — must stay empty
Recipient block	x 22, y 67, 85.5 × 23 mm

Template letters get this automatically. For your own PDF, place the recipient below 67 mm and verify with "delivery": "registered" — the verifier switches to the registered geometry and fails a normal-position address block. Registered mail is domestic-only and always uses the left field.

When you send with templateId, Dairo composites the recipient from the request’s to into this window at render time — a template must never contain an address of its own. The window only concerns you when you bring your own PDF.

Keep-out zones

These zones must contain nothing (except the address block itself inside the franking zone):

Zone	Geometry	Why
Franking, `left`	x 20, y 40, 89.5 × 47.5 mm	Postage/franking marks are stamped here
Franking, `right`	x 116, y 40, 89.5 × 47.5 mm	Same, for right-window letters
Page edges	5 mm on all sides, every page	Printer hardware margin
Bottom-left corner	15 × 15 mm	Postal processing marks
Left-margin routing code	x < 10 mm, y 124–134 mm	The carrier prints its sorting code here
Bottom band	110 mm, only with a payment slip	The generated slip is composited here

Two more PDF rules that bite in practice: no interactive form fields (AcroForm — flatten them, or the print output can lose content), and letters over 9 sheets ship unfolded in a C4 envelope automatically. Body content is safest starting at y ≥ 100 mm with 25 mm left / 20 mm right margins. The top band (y < 38 mm) is free for your letterhead, and the area right of the franking zone (x ≥ 112 mm, y 40–90 mm) fits a date/reference block.

Verify before sending

POST /v1/letters/verify takes the same document sources as the create (pdfBase64, file, or templateId + templateData + to) and returns a structured verdict — nothing is stored, mailed, or charged. Pass to so the address printed in the PDF is matched against the intended recipient.

curl -X POST https://api.dairo.app/v1/letters/verify \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfBase64": "JVBERi0xLjQK...",
    "to": {
      "name": "Jane Doe", "street": "Hauptstrasse", "houseNumber": "12",
      "postalCode": "8001", "city": "Zürich", "country": "CH"
    }
  }'

{
  "object": "letter_verification",
  "valid": false,
  "pageCount": 2,
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "addressPlacement": "left",
  "addressLines": ["Jane Doe", "Hauptstrasse 12", "8001 Zürich"],
  "checks": [
    { "id": "page_size", "status": "pass", "message": "All 2 page(s) are A4 portrait (210×297mm)." },
    { "id": "address_window", "status": "pass", "message": "Recipient address text found in the LEFT window (3 line(s))." },
    { "id": "address_match", "status": "pass", "message": "The printed address block matches the expected recipient." },
    { "id": "franking_zone", "status": "fail", "message": "1 text element(s) inside the franking keep-out (x=20–109.5mm, y=40–87.5mm) but outside the address window. This zone is reserved for postage/franking marks — move all content out of it." },
    { "id": "fonts_embedded", "status": "pass", "message": "Embedded font data found (3 font file(s))." }
  ],
  "summary": "1 check(s) failed — fix them and verify again before sending.",
  "agentHint": "Fix the failed checks, regenerate the PDF, and verify again. GET /v1/letters/requirements returns the exact layout spec (mm coordinates) and ready-made compliant starter templates."
}

valid is true only when no check failed. A fail means the letter will misprint or misroute — fix it. A warn means it will probably print but carries a risk (content near the page edge, unusually small address text, image-only pages the optical address reader may struggle with). The checks: page_size, page_count, address_window, address_fit, address_font_size, address_match (with to), franking_zone, edge_clearance, bottom_left_corner, fonts_embedded — each with the expected geometry in mm in its message, so a failing PDF can be regenerated without consulting anything else.

The safe sending workflow

GET /v1/letters/requirements — spec + starter templates (agents: start here).
Build the document (template or your own PDF).
POST /v1/letters/verify — fix every fail, review every warn.
POST /v1/letters/price — preview the cost.
POST /v1/letters with dryRun: true — a full no-send rehearsal: validated, rendered, priced; never mailed, never charged.
POST /v1/letters — the real send, with an Idempotency-Key.

Next steps

Letter templates — store branded, reusable letter HTML.
Print & delivery options — color, duplex, registered mail, payment slips.
Send a letter — the create call itself.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Layout & verification

The three ways to get a compliant PDF

Page setup

The address window

Registered mail is different

Keep-out zones

Verify before sending

The safe sending workflow

Next steps

​The three ways to get a compliant PDF

​Page setup

​The address window

​Registered mail is different

​Keep-out zones

​Verify before sending

​The safe sending workflow

​Next steps

The three ways to get a compliant PDF

Page setup

The address window

Registered mail is different

Keep-out zones

Verify before sending

The safe sending workflow

Next steps