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"
}

Field	Values	When to change it
`mode`	`grayscale` (default), `color`	`grayscale` is right for invoices, notices, and text-heavy documents. Use `color` for branded letterhead or anything where color carries meaning.
`sides`	`simplex` (default), `duplex`	`duplex` prints both sides of each sheet, so a longer document uses fewer sheets.
`addressPlacement`	`left` (default), `right`	Where the recipient address sits so it shows through the envelope window. Match it to your letterhead.

Delivery classes

The top-level delivery field sets the postal class.

Value	What it is
`economy`	The default — the standard class, the right pick for most mail.
`priority`	Expedited handling, where the destination offers it.
`registered`	Tracked delivery with delivery confirmation — for legal, contractual, and official mail.
`bulk`	A class for large, non-urgent mailings, where offered.
`premium`	The highest service tier, where offered.

Not every delivery class is available for every destination. Price the exact combination first with POST /v1/letters/price — it confirms the combination and returns what it costs. See Pricing.

Set the options on a create

Print and delivery ride on the same create call:

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": "8001", "city": "Zürich", "country": "CH"
    },
    "print": { "mode": "color", "sides": "duplex", "addressPlacement": "right" },
    "delivery": "registered"
  }'

await dairo.letters.create({
  pdfBase64: pdf.toString("base64"),
  fileName: "contract.pdf",
  to: {
    name: "Jane Doe",
    street: "Hauptstrasse",
    houseNumber: "12",
    postalCode: "8001",
    city: "Zürich",
    country: "CH",
  },
  print: { mode: "color", sides: "duplex", addressPlacement: "right" },
  delivery: "registered",
});

dairo.letters.create(
    pdf_base64=base64.b64encode(pdf).decode(),
    file_name="contract.pdf",
    to={
        "name": "Jane Doe",
        "street": "Hauptstrasse",
        "house_number": "12",
        "postal_code": "8001",
        "city": "Zürich",
        "country": "CH",
    },
    print={"mode": "color", "sides": "duplex", "address_placement": "right"},
    delivery="registered",
)

dairo letter send --pdf ./contract.pdf \
  --to-name "Jane Doe" --to-street "Hauptstrasse" --to-house-number 12 \
  --to-postal-code 8001 --to-city "Zürich" --to-country CH \
  --color --duplex --address-placement right \
  --delivery registered --confirm

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.

Scheme	Slip	Currency
`qr`	Swiss QR-bill	`CHF`
`sepaDe`	German SEPA payment slip with a GiroCode (EPC QR code)	`EUR`
`sepaAt`	Austrian SEPA payment slip with a GiroCode	`EUR`

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.

A generated payment slip is only available when Dairo renders the letter — pair it with a templateId, not pdfBase64 or file. Pairing payment with an inline PDF fails with 400 (“Payment slips require a template”). For a PDF that already draws its own slip, use the paymentSlip flag instead.

Field	Required	Description
`type`	yes	`qr`, `sepaDe`, or `sepaAt`.
`creditor.name`	yes	Name of the account holder being paid.
`creditor.iban`	yes	The IBAN to pay. For a Swiss QR-bill with a QR reference, use the QR-IBAN.
`creditor.country`	yes	Creditor country (ISO 3166-1 alpha-2).
`amount`	yes	The amount to pay, as a number greater than 0 with at most two decimals (`248.50`, not a string).
`currency`	no	Defaults to the scheme’s currency (`CHF` for `qr`, `EUR` for SEPA); when set it must match it.
`reference`	no	The structured payment reference — a Swiss QR/ISR reference for `qr`, or the remittance reference for SEPA. Encoded into the QR code so the recipient’s reference is prefilled.
`message`	no	Free-text note shown on the slip (unstructured remittance information).
`creditor.bic`, `creditor.street`, `creditor.houseNumber`, `creditor.postalCode`, `creditor.city`	no	Optional extra creditor details.
`debtor`	no	Optional payer block (`name`, `street`, `houseNumber`, `postalCode`, `city`, `country`); defaults to the letter recipient.

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"
    }
  }'

await dairo.letters.create({
  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.5,
    currency: "CHF",
    reference: "210000000003139471430009017",
  },
});

dairo.letters.create(
    template_id="ltpl_invoice",
    file_name="invoice-2026-06-118.pdf",
    to={
        "name": "Jane Doe",
        "street": "Hauptstrasse",
        "house_number": "12",
        "postal_code": "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 (German SEPA)

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

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Print & delivery options

Print options

Delivery classes

Set the options on a create

Payment slips (QR-bill, SEPA)

Generate the slip with a `payment` object

Bring your own slip with the `paymentSlip` flag

Stationery on the returned letter

Next steps

​Print options

​Delivery classes

​Set the options on a create

​Payment slips (QR-bill, SEPA)

​Generate the slip with a payment object

​Bring your own slip with the paymentSlip flag

​Stationery on the returned letter

​Next steps

Print options

Delivery classes

Set the options on a create

Payment slips (QR-bill, SEPA)

Generate the slip with a `payment` object

Bring your own slip with the `paymentSlip` flag

Stationery on the returned letter

Next steps