Print & delivery options

Every letter carries two groups of options: how it is printed (print) and how it travels (delivery). All of them are optional and all have defaults, so a minimal create is already a valid letter.

Print options

The print object controls the printing itself.

"print": {
  "mode": "grayscale",
  "sides": "duplex",
  "addressPlacement": "left"
}

Delivery classes

The top-level delivery field sets the postal class.

Any other value is a 400.

Supported destinations

Letters are printed and posted in Germany. Any country with an assigned ISO 3166-1 alpha-2 code is accepted as to.country, for example DE, AT, CH, FR, GB or US. A recipient in Germany is domestic, and every other country is international and priced as such. An unassigned code such as XX returns 422 with param: "to.country", on a price quote as well as on a send. GET /v1/letters/requirements lists the accepted countries under destinations. When destinations are restricted, that list names the accepted countries.

registered delivery is domestic only. The recipient must be in Germany.

Set the options on a create

Print and delivery ride on the same create call. Registered mail is domestic, so this example posts to a recipient in Germany:

curl -X POST https://api.dairo.app/v1/letters \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfBase64": "JVBERi0xLjQK...",
    "fileName": "contract.pdf",
    "to": {
      "name": "Jane Doe",
      "street": "Hauptstrasse", "houseNumber": "12",
      "postalCode": "10115", "city": "Berlin", "country": "DE"
    },
    "print": { "mode": "color", "sides": "duplex", "addressPlacement": "right" },
    "delivery": "registered"
  }'

Payment slips (QR-bill, SEPA)

Many European invoices ship with a payment slip — a region-standard, scannable slip the recipient uses to pay. There are two ways to add one: have Dairo generate the slip from a payment object, or bring your own slip already drawn in the PDF and declare it with the paymentSlip flag.

Match the scheme to the destination — qr for Switzerland, sepaDe for Germany, sepaAt for Austria. A slip only carries meaning in the region whose standard it follows.

Generate the slip with a payment object

Pass a payment object — the scheme type, the payee as a creditor block, and the amount — and Dairo renders a standards-compliant payment part full-width at the bottom of the letter, then prints the sheet on the matching stationery.

curl -X POST https://api.dairo.app/v1/letters \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "ltpl_invoice",
    "fileName": "invoice-2026-06-118.pdf",
    "to": {
      "name": "Jane Doe",
      "street": "Hauptstrasse", "houseNumber": "12",
      "postalCode": "8001", "city": "Zürich", "country": "CH"
    },
    "payment": {
      "type": "qr",
      "creditor": { "name": "Acme AG", "iban": "CH4431999123000889012", "country": "CH" },
      "amount": 248.50,
      "currency": "CHF",
      "reference": "210000000003139471430009017"
    }
  }'

A German SEPA slip is the same call with a different payment block — a sepaDe type, a EUR amount, and a German IBAN:

"payment": {
  "type": "sepaDe",
  "creditor": { "name": "Acme GmbH", "iban": "DE89370400440532013000", "country": "DE" },
  "amount": 129.00,
  "currency": "EUR",
  "reference": "Rechnung 2026-06"
}

Bring your own slip with the paymentSlip flag

If your PDF already lays out the QR-bill or SEPA slip — say your invoicing tool draws it exactly where you want — set paymentSlip to qr, sepaDe, or sepaAt instead of passing a payment object. The flag generates nothing; it declares the kind of slip your document already contains so the letter is printed on the right stationery.

{
  "pdfBase64": "JVBERi0xLjQK...",
  "fileName": "invoice-2026-06.pdf",
  "to": { "name": "Jane Doe", "street": "Hauptstrasse", "houseNumber": "12", "postalCode": "8001", "city": "Zürich", "country": "CH" },
  "paymentSlip": "qr"
}

Use either payment or paymentSlip, not both — payment makes Dairo draw the slip, paymentSlip declares one you drew yourself. Omit both for an ordinary letter.

Stationery on the returned letter

The returned letter reports its stationery in paperTypes — standard (the default), qr, sepa_de, or sepa_at — and echoes the chosen slip as paymentSlip (qr, sepaDe, sepaAt, or null), whether Dairo generated the slip or you supplied your own. A price request accepts the same paperTypes tokens so a quote can mirror the letter you plan to send.

Next steps

• Send a letter — use these options in a full create call.
• Letter templates — the render path that generated payment slips require.
• Status & tracking — follow the letter once it is posted.