---
title: "Render text into an A4 letter (DIN 5008) and create a draft"
method: POST
path: "/compose"
---

# Render text into an A4 letter (DIN 5008) and create a draft

`POST /compose`

## Request

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

## Request body

- object
  - `sender` Address, required
    - `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
  - `recipient` Address, required
    - `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
  - `subject` string, required
  - `body` string, required: Paragraphs separated by blank lines, '- ' bullets, **bold**
  - `language` string
  - `place` string
  - `date` string, date
  - `closing` string
  - `signature` string
  - `references` string[]
  - `duplex` boolean
  - `color` 'bw' | 'color'
  - `envelope` 'DL' | 'C5' | 'C4': Omit for the smallest envelope that fits
  - `registered` boolean

## Response `201`

Document and draft letter with price

- object
  - `document` Document
    - `id` string
    - `fileName` string
    - `pageCount` integer
    - `sizeBytes` integer: Size of the uploaded file
    - `compliant` boolean: Every page of the print file has the size of its paper (A4, or US Letter for a US Letter document) and keeps the free margin: the document can be sent
    - `hasColor` boolean
    - `fixed` boolean: A margin fix (shrink or crop) is applied
    - `fixMode` 'shrink' | 'crop' | 'null', nullable
    - `fixedAt` string, date-time, nullable
    - `source` 'upload' | 'url' | 'compose'
    - `printedOn` 'A4' | 'US Letter': The paper size uploaded is the paper printed on: "US Letter" when every page is US Letter (8.5 × 11 in), else "A4" (A4 documents, and documents mixing A4 and US Letter pages). A letter with a US Letter document to a destination outside the US, Canada and US territories is printed on the paper the customer chose (Letter paperSize).
    - `usLetterPages` integer: Uploaded US Letter pages: every page of a US Letter document (printed on US Letter paper, checked with the same margin), or the US Letter pages of a mixed document, which the print file centres on A4 sheets at 100 % or scales down just enough when their content would otherwise come within the margin (analysis.pages[].usLetter.scale, 1 = 100 %). The original upload is kept.
    - `usLetterNote` string, nullable: How the US Letter pages are printed, e.g. "The document is printed on US Letter paper, as uploaded. …" or "The US Letter page is printed on A4 paper, centred at 100%."; null without any
    - `analysis` object: Print check of the print file: marginMm, compliant (decides whether it can be printed), allA4 (literally every page A4: false for a printable US Letter document), paper ("a4" or "us_letter"), usLetterPages, a4Version (a US Letter document's version on A4: compliant, scales per page), and per page (pages[]) widthMm, heightMm, isA4, isUsLetter, orientation, contentBox, violations (side, depthMm), usLetter ({ scale } on US Letter pages placed on A4)
    - `createdAt` string, date-time
    - `deleteAfter` string, date-time
  - `letter` 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)