Letter design

1. 1

   What is a letter design?

   A letter design is your reusable letterhead: a header band with a logo (top, beside the sender, or as a full-page background that can also replace the server-drawn sender block), a DIN 5008 info block in the top right (Ihr Zeichen, Unser Zeichen, Vorgangsnummer, customer number, date, and up to four custom fields), a classic footer with 1 to 4 columns, a QR or Code128 barcode generated at compose time, and fold and hole marks in the left margin. You save a letter design once per partner account under a name and reference it afterwards by designId on any send. Every element is checked against the DIN 5008 and Pingen/LetterXPress delivery clear zones (address window, franking zone, letter body area) before it is ever used on a send, so a design can never accidentally jeopardize delivery.

2. 2

   Save a design (letter_design_save)

   letter_design_save takes a name and the complete design JSON and checks both immediately: the field bounds (Zod schema) and the delivery clear zones (e.g. the info block must not reach into the address window). An invalid design is rejected with DESIGN_ZONE_VIOLATION and a precise violations list, before it is ever saved. Without a designId it is created or overwritten by name, with a designId you update an existing design. The response returns designId and a stable designHash that later lets you trace every order that used this design.

   letter_design_save
   {
     "name": "Kanzlei-Standard",
     "design": {
       "schemaVersion": 1,
       "header": {
         "letterheadId": "7e2a1c9d-4f3b-4a12-9c8e-1a2b3c4d5e6f",
         "placement": "top",
         "widthMm": 60,
         "heightMm": 20,
         "offsetYMm": 8
       },
       "infoblock": {
         "enabled": true,
         "rows": [
           {
             "key": "unser_zeichen",
             "label": "Unser Zeichen",
             "staticValue": "AB-2026"
           },
           {
             "key": "vorgangsnummer",
             "label": "Vorgang",
             "staticValue": null
           },
           {
             "key": "datum",
             "label": "Datum",
             "staticValue": null
           }
         ]
       },
       "footer": {
         "enabled": true,
         "scope": "first-page",
         "columns": [
           [
             "Kanzlei Mueller",
             "Musterstr. 1",
             "12345 Musterstadt"
           ],
           [
             "Tel 030 1234",
             "info@kanzlei-mueller.de"
           ]
         ]
       },
       "barcode": {
         "enabled": true,
         "type": "qr",
         "placement": "infoblock",
         "payloadTemplate": "https://portal.kanzlei.de/v/{{vorgangsnummer}}"
       },
       "falzmarken": {
         "enabled": true
       }
     }
   }

3. 3

   Preview (letter_design_preview)

   Before you use a design, you see it: letter_design_preview composes a sample page with your design (saved by designId or an inline not-yet-saved design) and returns a short-lived preview link (valid for 15 minutes). Nothing is charged and nothing is sent, no order is created. Optionally pass reference with sample values, so the info block and barcode look exactly like they would on the real letter.

   letter_design_preview
   {
     "designId": "<designId from letter_design_save>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     }
   }

4. 4

   Send with a Vorgangsnummer (order_send with designId + reference)

   On order_send (and order_send_batch, letter_draft) you pass designId and reference. designId selects the letter design for this one letter, if omitted the sender profile default design applies, otherwise none. reference supplies the values your info block rows and your barcode payload need for this one letter (e.g. vorgangsnummer, ihrZeichen, customer number, or a custom value under values). If a value a row or the barcode placeholder requires is missing, the send aborts BEFORE any charge, so a letter with an empty Vorgangsnummer field or a dead QR code is never sent.

   order_send
   {
     "clientOrderId": "objection-schmidt-2026-07-05",
     "subject": "Objection to tax assessment dated 2026-05-15",
     "content": "Dear Sir or Madam, ...",
     "recipientCompany": "Finanzamt Muenchen-Land",
     "recipientStreet": "Postfach 12 52",
     "recipientZip": "80292",
     "recipientCity": "Muenchen",
     "recipientCountry": "DE",
     "designId": "<designId from letter_design_save>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     }
   }

5. 5

   Error handling

   Three new error codes belong to letter design, all agent-fixable (recoverable from the response alone): DESIGN_NOT_FOUND (404) means the designId does not exist or does not belong to your account, check the id or list your designs with letter_design_list. DESIGN_RENDER_FAILED (422) means a value for the info block or barcode is missing, supply the named value in reference. DESIGN_ZONE_VIOLATION (422) means a design box violates a delivery clear zone, adjust the named position/size per violations. The full description of each code lives in the error catalog, the field reference for every tool in the tool reference.

See the tool reference →See the error catalog →