> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Layout & verification

> The exact PDF layout a printed letter needs — address window, keep-out zones, fonts — plus the verify endpoint that checks a PDF before you send it.

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](/api-reference/dairo-api/letters/get-letter-requirements) | `GET /v1/letters/requirements` | `letters:read` |
| [Verify a letter](/api-reference/dairo-api/letters/verify-letter)            | `POST /v1/letters/verify`      | `letters:read` |

<Tip>
  **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.
</Tip>

## The three ways to get a compliant PDF

1. **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.
2. **Store your own template.** Write your own HTML (brand, layout, fonts) that
   keeps the zones below clear, store it as a [letter template](/letters/templates),
   and let Dairo render + place the address.
3. **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.

<Note>
  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.
</Note>

## 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](/letters/print-delivery) | 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.

<CodeGroup>
  ```bash title="cURL" theme={null}
  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"
      }
    }'
  ```

  ```json title="Response" theme={null}
  {
    "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."
  }
  ```
</CodeGroup>

`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

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

## Next steps

* [Letter templates](/letters/templates) — store branded, reusable letter HTML.
* [Print & delivery options](/letters/print-delivery) — color, duplex, registered mail, payment slips.
* [Send a letter](/letters/sending-a-letter) — the create call itself.