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.
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.
How it works
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 with
POST /v1/letters/verify first — GET /v1/letters/requirements returns
the machine-readable spec plus compliant starter templates.
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.
Pick print and delivery
Color or grayscale, one side or two, and a delivery class (economy,
priority or registered). Every option has a default, so a minimal request works.
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.
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.
A letter is one call
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.
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.
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 |
| Payment slip | paymentSlip | omit for none (default), qr, sepaDe, sepaAt |
Go deeper
Send a letter
Create, list, get, cancel, and price — the full API walkthrough in cURL, TypeScript, Python, and the CLI.
Print & delivery options
Color vs. grayscale, simplex vs. duplex, delivery classes, and payment slips.
Status & tracking
The status lifecycle, the event timeline, webhook events, and owner email notifications.
Letter templates
Design the branded letter once, leave the address window blank, and send by id.
Send a batch
One template, up to 1,000 recipients, in a single call.
Pricing
Get the exact cost of a letter before you send it.