Send a letter

Create a letter from a PDF and a postal address, then follow it by id. This page covers the core letter operations; letter templates and batches have their own pages.

Operation	Method & path	Scope
Create a letter	`POST /v1/letters`	`letters:send`
List letters	`GET /v1/letters`	`letters:read`
Get a letter	`GET /v1/letters/{id}`	`letters:read`
Cancel a letter	`POST /v1/letters/{id}/cancel`	`letters:send`
List letter events	`GET /v1/letters/{id}/events`	`letters:read`
Price a letter	`POST /v1/letters/price`	`letters:read`

Create a letter

Pass the PDF as pdfBase64, a fileName, and a recipient to address. Everything else has defaults.

curl -X POST https://api.dairo.app/v1/letters \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-inv_123" \
  -d '{
    "pdfBase64": "JVBERi0xLjQK...",
    "fileName": "invoice-2026-06.pdf",
    "to": {
      "name": "Jane Doe",
      "company": "Acme GmbH",
      "street": "Hauptstrasse",
      "houseNumber": "12",
      "postalCode": "8001",
      "city": "Zürich",
      "country": "CH"
    },
    "print": { "mode": "grayscale", "sides": "duplex", "addressPlacement": "left" },
    "delivery": "economy",
    "metadata": { "invoiceId": "inv_123" }
  }'

const letter = await dairo.letters.create(
  {
    pdfBase64: pdf.toString("base64"),
    fileName: "invoice-2026-06.pdf",
    to: {
      name: "Jane Doe",
      company: "Acme GmbH",
      street: "Hauptstrasse",
      houseNumber: "12",
      postalCode: "8001",
      city: "Zürich",
      country: "CH",
    },
    print: { mode: "grayscale", sides: "duplex", addressPlacement: "left" },
    delivery: "economy",
    metadata: { invoiceId: "inv_123" },
  },
  { idempotencyKey: "invoice-inv_123" },
);
console.log(letter.id, letter.status); // let_… queued

letter = dairo.letters.create(
    pdf_base64=base64.b64encode(pdf).decode(),
    file_name="invoice-2026-06.pdf",
    to={
        "name": "Jane Doe",
        "company": "Acme GmbH",
        "street": "Hauptstrasse",
        "house_number": "12",
        "postal_code": "8001",
        "city": "Zürich",
        "country": "CH",
    },
    print={"mode": "grayscale", "sides": "duplex", "address_placement": "left"},
    delivery="economy",
    metadata={"invoiceId": "inv_123"},
    idempotency_key="invoice-inv_123",
)
print(letter.id, letter.status)  # let_… queued

dairo letter send \
  --pdf ./invoice-2026-06.pdf \
  --to-name "Jane Doe" --to-company "Acme GmbH" \
  --to-street "Hauptstrasse" --to-house-number 12 \
  --to-postal-code 8001 --to-city "Zürich" --to-country CH \
  --grayscale --duplex --address-placement left \
  --delivery economy \
  --confirm

The response is the letter object at status: "queued" — accepted and being prepared, nothing printed yet. pageCount and price are null until the letter is priced.

{
  "object": "letter",
  "id": "let_01HZX...",
  "status": "queued",
  "fileName": "invoice-2026-06.pdf",
  "pageCount": null,
  "to": {
    "name": "Jane Doe", "company": "Acme GmbH",
    "street": "Hauptstrasse", "houseNumber": "12",
    "postalCode": "8001", "city": "Zürich", "country": "CH"
  },
  "print": { "mode": "grayscale", "sides": "duplex", "addressPlacement": "left" },
  "delivery": "economy",
  "paymentSlip": null,
  "autoSend": true,
  "notifications": true,
  "price": null,
  "trackingNumber": null,
  "metadata": { "invoiceId": "inv_123" },
  "submittedAt": null,
  "createdAt": "2026-06-22T10:01:02Z",
  "updatedAt": "2026-06-22T10:01:02Z"
}

Always pass an Idempotency-Key header (or idempotencyKey in the SDKs) when creating letters. A retried create with the same key returns the original letter instead of printing a second one — physical mail cannot be unsent. See Retries & idempotency. In the CLI, dairo letter send creates a draft unless you pass --confirm, so an accidental rerun never posts anything.

Document sources

A letter’s document comes from exactly one of three sources:

Source	What it is
`pdfBase64`	The PDF inline, base64-encoded.
`file`	A PDF already in Dairo — either an email attachment (`attachmentId`, with an optional informational `messageId`) or a storage object (`objectId`). Exactly one of the two; the storage object must have passed its malware scan.
`templateId`	A stored letter template, rendered with `templateData` and the recipient composited into the address window.

file: reuse an email attachment

{
  "file": { "attachmentId": "att_9f2c", "messageId": "msg_abc" },
  "fileName": "invoice-2026-06.pdf",
  "to": { "name": "Jane Doe", "street": "Hauptstrasse", "houseNumber": "12", "postalCode": "8001", "city": "Zürich", "country": "CH" }
}

file: reuse a storage object

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

The document must be a real PDF no larger than 25 MB. A non-PDF is rejected with 422; an oversize file with 413. Providing more than one source — or none — is a 400.

Bringing your own PDF? It must follow the layout contract — A4 portrait, the recipient address inside the envelope window, franking zones clear, fonts embedded. POST /v1/letters/verify checks all of it and returns a structured pass/warn/fail report before anything is printed; GET /v1/letters/requirements returns the machine-readable spec plus compliant starter templates.

Request fields

Field	Required	Description
`pdfBase64` / `file` / `templateId`	one of	The document source — exactly one of the three.
`fileName`	yes	A name for the document, kept for your records.
`to`	yes	Recipient postal address. `country` (ISO 3166-1 alpha-2) is required, plus a `street` or a `poBox`.
`from`	no	Optional sender block, same shape as `to`.
`print`	no	`mode`, `sides`, `addressPlacement`. Defaults: `grayscale`, `simplex`, `left`.
`delivery`	no	Delivery class; defaults to `economy`.
`autoSend`	no	`true` (default) queues the letter for posting; `false` stores it as a `draft`.
`templateData`	no	Values that fill the template’s `{{placeholders}}`; used only with `templateId`.
`payment` / `paymentSlip`	no	Add a payment slip — see Print & delivery options.
`notifications`	no	Owner milestone emails for this letter; defaults to `true`.
`metadata`	no	Opaque JSON object (up to 8 KB), stored and echoed back.

The recipient’s country must be a destination Dairo can deliver to. An unsupported or malformed country is rejected with 422 naming to.country.

List letters

List your letters, most recent first. Page with limit (1–100, default 20) and cursor using keyset pagination, and filter by status, country, or batchId.

curl "https://api.dairo.app/v1/letters?limit=20&status=in_transit" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const page = await dairo.letters.list({ limit: 20, status: "in_transit" });
for (const letter of page.data) console.log(letter.id, letter.status);

page = dairo.letters.list(limit=20, status="in_transit")
for letter in page.data:
    print(letter.id, letter.status)

dairo letter list --limit 20 --status in_transit

List items are compact: the to block carries only the recipient’s city and country, never the full address.

{
  "object": "list",
  "data": [
    {
      "object": "letter",
      "id": "let_01HZX...",
      "status": "in_transit",
      "fileName": "invoice-2026-06.pdf",
      "to": { "city": "Zürich", "country": "CH" },
      "delivery": "economy",
      "trackingNumber": "RR123456785CH",
      "createdAt": "2026-06-22T10:01:02Z"
    }
  ],
  "pagination": { "nextCursor": "eyJjcmVhdGVkX2F0Ijoi...", "hasMore": true }
}

Get one letter

Fetch a letter by id to read its current status, price, any trackingNumber, and its full address, with the delivery events timeline inlined newest first (up to 100 events). Fetching an in-flight letter also refreshes its tracking state, so a poll returns the latest known status.

curl https://api.dairo.app/v1/letters/let_01HZX \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const letter = await dairo.letters.get("let_01HZX");
console.log(letter.status, letter.trackingNumber);
for (const e of letter.events) console.log(e.type, e.occurredAt);

letter = dairo.letters.get("let_01HZX")
print(letter.status, letter.tracking_number)
for e in letter.events:
    print(e.type, e.occurred_at)

dairo letter get let_01HZX

{
  "object": "letter",
  "id": "let_01HZX...",
  "status": "in_transit",
  "trackingNumber": "RR123456785CH",
  "price": { "currency": "eur", "amount": 0.92 },
  "pageCount": 3,
  "to": {
    "name": "Jane Doe", "street": "Hauptstrasse", "houseNumber": "12",
    "postalCode": "8001", "city": "Zürich", "country": "CH"
  },
  "print": { "mode": "grayscale", "sides": "duplex", "addressPlacement": "left" },
  "delivery": "economy",
  "events": [
    {
      "object": "letter_event",
      "eventId": "lev_2",
      "type": "in_transit",
      "code": "handed_to_carrier",
      "description": "Handed to postal carrier",
      "occurredAt": "2026-06-23T08:00:00Z"
    }
  ],
  "createdAt": "2026-06-22T10:01:02Z",
  "updatedAt": "2026-06-23T08:00:11Z"
}

A letter id that is unknown or not yours returns 404 — the two cases are indistinguishable by design.

Cancel a letter

Cancel a letter that has not been dispatched. Cancellation is allowed while the letter is draft, queued, processing, printable, or submitted — once it is in_transit it is in the postal network and cannot be recalled.

curl -X POST https://api.dairo.app/v1/letters/let_01HZX/cancel \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const canceled = await dairo.letters.cancel("let_01HZX");
console.log(canceled.status); // canceled

canceled = dairo.letters.cancel("let_01HZX")
print(canceled.status)  # canceled

dairo letter cancel let_01HZX

You get back the letter with status: "canceled" and canceledAt set. Canceling a letter that is already past dispatch returns 409 Conflict with code: "letter_not_cancelable".

List a letter’s events

Fetch the delivery timeline on its own. Events come back newest first, up to the 100 most recent.

curl https://api.dairo.app/v1/letters/let_01HZX/events \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const events = await dairo.letters.listEvents("let_01HZX");
for (const e of events.data) console.log(e.type, e.code, e.occurredAt);

events = dairo.letters.list_events("let_01HZX")
for e in events.data:
    print(e.type, e.code, e.occurred_at)

dairo letter events let_01HZX

{
  "object": "list",
  "data": [
    {
      "object": "letter_event",
      "eventId": "lev_1",
      "letterId": "let_01HZX...",
      "type": "submitted",
      "code": "submitted_for_print",
      "description": "Submitted to print center",
      "hasImage": false,
      "occurredAt": "2026-06-22T10:05:00Z",
      "recordedAt": "2026-06-22T10:05:03Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

The event field reference is on Status & tracking.

Price a letter

A letter’s cost depends on its page count, print options, delivery class, and destination. POST /v1/letters/price returns the exact cost without creating a letter — pass a pageCount, or the pdfBase64 itself and Dairo counts the pages.

cURL

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

The full request reference, the quote-then-send pattern, and how letters bill are on Pricing.

Next steps

Send a batch — one template, up to 1,000 recipients, in one call.
API reference — full request and response schemas for every letters endpoint.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Create a letter

Document sources

Request fields

List letters

Get one letter

Cancel a letter

List a letter’s events

Price a letter

Next steps

​Create a letter

​Document sources

​Request fields

​List letters

​Get one letter

​Cancel a letter

​List a letter’s events

​Price a letter

​Next steps

Create a letter

Document sources

Request fields

List letters

Get one letter

Cancel a letter

List a letter’s events

Price a letter

Next steps