> ## 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.

# Physical mail (Fairo)

> Turn a PDF into a real, printed letter — one API call, then Dairo prints, posts, and tracks it to the mailbox.

Send a real, printed letter with one API call. Give Dairo a PDF and a postal
address; Dairo prints it, encloses it, posts it, and tracks it to the mailbox.
Fairo is the physical-mail side of Dairo — the same API and keys you already
use for email, pointed at the postal network.

<Note>
  Letters use two scopes: `letters:read` for listing, fetching, delivery events,
  and price quotes; `letters:send` for creating and canceling letters, and for
  creating batches and templates.
</Note>

## How it works

<Steps>
  <Step title="Provide the document">
    Pass the PDF inline as `pdfBase64`, reference a file already in Dairo with
    `file` (an email attachment or a storage object), or render a stored letter
    template by `templateId`. Exactly one source per letter, plus a `fileName`
    for your records. Bringing your own PDF? Check it against the
    [layout contract](/letters/layout-and-verification) with
    `POST /v1/letters/verify` first — `GET /v1/letters/requirements` returns
    the machine-readable spec plus compliant starter templates.
  </Step>

  <Step title="Address it">
    Set the recipient in `to`, with an optional `from` sender block. `country`
    (ISO 3166-1 alpha-2) is required, and the address needs a `street` or a
    `poBox`.
  </Step>

  <Step title="Pick print and delivery">
    Color or grayscale, one side or two, and a delivery class from `economy`
    to `premium`. Every option has a default, so a minimal request works.
  </Step>

  <Step title="Send it">
    `autoSend: true` (the default) queues the letter for printing and posting.
    `autoSend: false` stores it as a `draft` instead — nothing is printed, and
    you can still cancel it.
  </Step>

  <Step title="Track it to the mailbox">
    Dairo follows the letter for you. Read its `status` and event timeline
    back by `id`, subscribe to `letter.status_changed` webhook events, or have
    Dairo email you at each delivery milestone.
  </Step>
</Steps>

## A letter is one call

```bash title="cURL" theme={null}
curl -X POST https://api.dairo.app/v1/letters \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfBase64": "JVBERi0xLjQK...",
    "fileName": "invoice-2026-06.pdf",
    "to": {
      "name": "Jane Doe",
      "street": "Hauptstrasse",
      "houseNumber": "12",
      "postalCode": "8001",
      "city": "Zürich",
      "country": "CH"
    },
    "delivery": "economy"
  }'
```

You get back a `letter` object with an `id` and `status: "queued"`. From there
the letter moves through the lifecycle — printed, posted, in transit,
delivered — and Dairo keeps its status and delivery events current.

<Warning>
  Physical mail is irreversible once it is in the postal network. You can cancel
  a letter while its status is `draft`, `queued`, `processing`, `printable`, or
  `submitted` — never once it is `in_transit`. Quote first with
  `POST /v1/letters/price` and pass an idempotency key on create so a retry can
  never print the same letter twice.
</Warning>

## Options at a glance

| Option            | Field                    | Values                                                           |
| ----------------- | ------------------------ | ---------------------------------------------------------------- |
| Print color       | `print.mode`             | `grayscale` (default), `color`                                   |
| Sides             | `print.sides`            | `simplex` (default), `duplex`                                    |
| Address placement | `print.addressPlacement` | `left` (default), `right`                                        |
| Delivery class    | `delivery`               | `economy` (default), `priority`, `registered`, `bulk`, `premium` |
| Payment slip      | `paymentSlip`            | omit for none (default), `qr`, `sepaDe`, `sepaAt`                |

## Go deeper

<CardGroup cols={2}>
  <Card title="Send a letter" icon="paper-plane" href="/letters/sending-a-letter">
    Create, list, get, cancel, and price — the full API walkthrough in cURL,
    TypeScript, Python, and the CLI.
  </Card>

  <Card title="Print & delivery options" icon="print" href="/letters/print-delivery">
    Color vs. grayscale, simplex vs. duplex, delivery classes, and payment
    slips.
  </Card>

  <Card title="Status & tracking" icon="timeline" href="/letters/status-lifecycle">
    The status lifecycle, the event timeline, webhook events, and owner email
    notifications.
  </Card>

  <Card title="Letter templates" icon="file-lines" href="/letters/templates">
    Design the branded letter once, leave the address window blank, and send
    by id.
  </Card>

  <Card title="Send a batch" icon="layer-group" href="/letters/batches">
    One template, up to 1,000 recipients, in a single call.
  </Card>

  <Card title="Pricing" icon="calculator" href="/letters/pricing">
    Get the exact cost of a letter before you send it.
  </Card>
</CardGroup>