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

# Pricing

> A letter's price depends on pages, print, delivery, and destination — get the exact cost before you send with priceLetter.

A letter does not have one flat price the way an email does. What it costs
depends on how many pages it is, how it is printed and delivered, and where it
is going. `POST /v1/letters/price` returns the exact cost for any combination —
without creating a letter.

## Price a letter

Send the destination `country` and either a `pageCount` or the PDF itself as
`pdfBase64` — the only difference is who counts the pages. Add the same
`print` and `delivery` options you plan to send with, so the quote matches the
real letter.

<CodeGroup>
  ```bash title="cURL" theme={null}
  curl -X POST https://api.dairo.app/v1/letters/price \
    -H "Authorization: Bearer $DAIRO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "country": "CH",
      "pageCount": 3,
      "print": { "mode": "grayscale", "sides": "duplex" },
      "delivery": "economy"
    }'
  ```

  ```ts title="TypeScript" theme={null}
  const quote = await dairo.letters.price({
    country: "CH",
    pageCount: 3,
    print: { mode: "grayscale", sides: "duplex" },
    delivery: "economy",
  });
  console.log(`${quote.amount} ${quote.currency}`); // 0.92 eur
  ```

  ```python title="Python" theme={null}
  quote = dairo.letters.price(
      country="CH",
      page_count=3,
      print={"mode": "grayscale", "sides": "duplex"},
      delivery="economy",
  )
  print(quote.amount, quote.currency)  # 0.92 eur
  ```

  ```bash title="CLI" theme={null}
  dairo letter price --country CH --page-count 3 \
    --grayscale --duplex \
    --delivery economy
  ```
</CodeGroup>

You get back a `letter_price` object. `amount` and `currency` are the price
you are billed for a letter sent with the same page count and options.

```json theme={null}
{
  "object": "letter_price",
  "currency": "eur",
  "amount": 0.92,
  "country": "CH",
  "pageCount": 3,
  "delivery": "economy",
  "print": { "mode": "grayscale", "sides": "duplex" }
}
```

### Request fields

| Field        | Required | Description                                                                                                     |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `country`    | yes      | Destination country (ISO 3166-1 alpha-2). Postage depends on the destination.                                   |
| `pageCount`  | one of   | The number of pages to price (minimum 1). The quote is page-aware, so send the real count.                      |
| `pdfBase64`  | one of   | The PDF itself; Dairo counts its pages for you.                                                                 |
| `print`      | no       | `mode` and `sides` — both are part of the quote. Defaults: `grayscale`, `simplex`.                              |
| `delivery`   | no       | Delivery class; defaults to `economy`.                                                                          |
| `paperTypes` | no       | Payment-slip stationery: `standard` (default), `qr`, `sepa_de`, `sepa_at` — mirror the letter you plan to send. |

Not every delivery class is available for every destination — a successful
quote confirms the combination before you commit to it.

## Quote first, then send

Pricing needs only `letters:read`, so a read-only key — or an agent in a
planning step — can quote a letter before anything is created. Physical mail
cannot be unsent, so quote first and send only when the projected cost is
inside whatever ceiling you enforce for the workload:

```ts title="TypeScript" theme={null}
const SPEND_CAP_EUR = 5.0; // your own per-run ceiling for this workload

const quote = await dairo.letters.price({ country: "CH", pageCount: 3, delivery: "economy" });
if (quote.amount <= SPEND_CAP_EUR) {
  await dairo.letters.create({ pdfBase64, fileName: "notice.pdf", to, delivery: "economy" });
}
```

Dairo enforces a ceiling of its own: letters count against your account's
[send budget](/agents/reputation), with each page counting as one unit, and a
create that would breach the budget is rejected before anything is printed.

## How letters bill

Letters are metered separately from email and billed per letter at the
letter's own priced amount — each letter costs what its pages, options, and
destination add up to, which is the same calculation the price endpoint runs.
A letter that fails validation or production before the print handoff is not
billed. For how metering and billing work across the platform, see
[Plans & pricing](/platform/enterprise-plans).

## Next steps

* [Send a letter](/letters/sending-a-letter) — turn a quote into a real letter.
* [Send a batch](/letters/batches) — project and send a whole templated run.