---
title: "GET /letters"
method: GET
path: "/letters"
---

# GET /letters

`GET /letters`

## Request

- Base URL: `https://printandmailcompany.com/api/v1`
- URL: `https://printandmailcompany.com/api/v1/letters`
- Auth: HTTP bearer

## Query parameters

- `status` string
- `limit` integer

## Response `200`

Letters, newest first

- object
  - `letters` Letter[]
    - `id` string
    - `reference` string: Shown to the customer and on receipts, e.g. PM-7K3QX9
    - `status` 'draft' | 'paid' | 'in_production' | 'printed' | 'posted' | 'cancelled' | 'returned'
    - `documentId` string
    - `recipient` Address
      - `name` string, required
      - `company` string
      - `line1` string, required: Street and number or PO box
      - `line2` string
      - `postalCode` string
      - `city` string, required
      - `region` string: State/province where used (e.g. US state code)
      - `country` string, required: ISO 3166-1 alpha-2
    - `recipientLines` string[]: The address as printed on the envelope
    - `options` object
      - `pages` integer
      - `duplex` boolean
      - `color` 'bw' | 'color'
      - `envelope` 'DL' | 'C5' | 'C4'
      - `registered` boolean
      - `paper` 'a4' | 'us_letter' | 'null', nullable: Paper the letter is printed on, fixed at payment; null while the paper choice is pending; absent on letters from before 8 October 2026 (A4)
      - `paperChoice` 'a4' | 'us_letter': The paper the customer chose for a US Letter document to a destination outside the US, Canada and US territories
    - `paperSize` 'a4' | 'us_letter' | 'null', nullable: Paper the letter is printed on (a draft's as decided from its document now, a paid letter's as fixed at payment); null while the customer still has to choose (paperChoiceRequired)
    - `paperChoiceRequired` boolean: A US Letter document to a destination outside the US, Canada and US territories, and no choice yet: ask "shrink to A4 (recommended) or keep US Letter?" and send paperSize with /letters/{id}/send. Sending without it answers 409 PAPER_CHOICE_REQUIRED.
    - `destinationPaperSize` 'a4' | 'us_letter': Standard paper of the destination: us_letter for US, CA, PR, VI, GU, AS, MP, else a4
    - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF'
    - `total` integer: Total in minor units of currency
    - `totalFormatted` string
    - `quote` object: Price breakdown in EUR cents (lines, netEurCents, vatEurCents, grossEurCents, vatRate, reverseCharge), postal size class and zone
    - `priceLabel` string: "incl. 17% VAT", or "excl. VAT — reverse charge"
    - `trackingNumber` string, nullable: Registered letters, once posted
    - `createdVia` 'web' | 'mcp' | 'api'
    - `createdAt` string, date-time
    - `paidAt` string, date-time, nullable
    - `postedAt` string, date-time, nullable
    - `cancelledAt` string, date-time, nullable
    - `url` string, uri: The letter's page in the customer's account, in the account's language: the print-ready PDF (page previews, open, download) until the retention period ends, the status and the price. Give it to the account holder to check the letter before sending; it needs their sign-in.

---

[API](https://skmtc.dev/printandmailcompany/apis/print-and-mail-company-api.md) · [All operations](https://skmtc.dev/printandmailcompany/apis/print-and-mail-company-api/llms.txt) · [OpenAPI document](https://skmtc.dev/printandmailcompany/apis/print-and-mail-company-api/revisions/0d0b97806499?raw)