Pricing

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 one page source: a pageCount, the PDF itself as pdfBase64, a stored file, or a stored templateId. 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.

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

You get back a letter_price object. amount and currency are the price of a letter sent with the same page count and options. Your credits wallet is in USD, so walletAmount and walletCurrency show what the letter takes from it, at the same conversion rate the charge uses. walletRate is that rate: walletAmount is amount × walletRate, rounded to the cent. The rate is set slightly above the market rate so currency moves never leave a letter under-charged. Currency codes are always upper-case. A letter's own price object carries the same wallet fields once it is priced.

This page quotes no amounts on purpose: postage and print prices follow the print partner's rates and change over time, so quote the letter you are about to send and budget from that answer, not from an example.

Request fields

When you send more than one page source, the first one in the table wins. A request with none is a 400 whose param is pageCount.

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:

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, with each page counting as one unit, and a create that would breach the budget is rejected before anything is printed.

How letters bill

Each letter is charged to your credits wallet at its own priced amount (walletAmount): what its pages, options, and destination add up to, the same calculation the price endpoint runs. A letter that fails validation or production before the print handoff is not charged, and a create the wallet cannot cover is rejected with insufficient_credits.

Next steps

• Send a letter — turn a quote into a real letter.
• Send a batch — project and send a whole templated run.