Dedicated tool guide

letter_create_draft

Create and persist a free letter draft, then inspect the returned preview before any send.

Generated contract: apiVersion v1, schemaRevision 2. Examples use placeholders and do not call production.

`letter_create_draft`

actionscope: order:send

Creates a letter draft: produces a preview PDF in the stored letter design (letter body only), stores the draft and returns page count, preview link (valid for 24 hours) and a non-binding cost estimate. The draft stays free of charge until it is sent. The body is either content (plain text) OR blocks (structured: tables, headings, totals lines), exactly one of the two. Compact blocks example: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema reference incl. styleDefs and limits: MCP resource frankki://blocks-guide. The first pages come back as images and show subject, address in the address window, sender, date and line breaks as they will print. The embedded card is the human preview; the PDF link and letter text are also in the result, for text-only views. Reported findings are in warnings. A new call creates a corrected draft; a printed letter is final. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. Next step with the returned letterId: letter_preview shows the draft as an image to refine it, order_send sends the draft, letter_schedule sends it at a later time.

Input contract

Field	Type	Requirement	Meaning
`subject`	string	required
`content`	string	optional	Letter body as plain text. Exactly one of content and blocks.
`blocks`	array<object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object>	optional	Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes.
`styleDefs`	object	optional	Named document styles (max 24); blocks reference them via style.
`language`	de \| en	optional	Defaults to de.
`senderAddressId`	string	optional
`senderProfileId`	string	optional	Sender profile the letter will later be sent with. For the preview only its default letter design is used.
`recipientAddressId`	string	optional	A saved address from the address book (address_list) as the recipient. Equivalent: recipientAddressInline or the fields recipientName to recipientCountry as on order_send.
`recipientName`	string	optional
`recipientCompany`	string	optional
`recipientStreet`	string	optional
`recipientHouseNumber`	string	optional
`recipientZip`	string	optional
`recipientCity`	string	optional
`recipientCountry`	string	optional
`recipientAddressInline`	object	optional
`presetName`	string	optional
`includeSignature`	boolean	optional	true places the stored signature under the letter text. Off by default, same as on send.
`signatureId`	string	optional	A specific stored signature in place of the first one on file.
`clientLetterId`	string	optional	Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content ends with IDEMPOTENCY_CONFLICT and creates no draft.
`designId`	string	optional	Saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send.
`reference`	object	optional	Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode.

Contract-shaped example

letter_create_draft({
  "subject": "Contract notice",
  "content": "Dear Sir or Madam,\n\nPlease confirm receipt.",
  "clientLetterId": "contract-482-notice-v1",
  "language": "en"
})

Use the returned letterId with letter_preview, then price the reviewed draft with shipping_quote.

For conditional fields and nested object limits, the generated complete tool reference remains authoritative. See errors and safe agent onboarding before implementing retries or a live send.

Trust and live status

Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.

Service facts (JSON) ↗Live status ↗