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 1. Examples use placeholders and do not call production.
letter_create_draft
actionscope: order:sendCreates a letter draft: produces a preview PDF in the stored letter design (letter body only), stores the draft and returns a page count, a preview link (valid for 24 hours) and a non-binding cost estimate. The draft stays free of charge until you send it. 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}]}]} Full reference incl. styleDefs and limits: MCP resource frankki://blocks-guide. The first pages come back as images: look at them before sending and check the subject, the address inside the address window, sender, date and line breaks. Reported findings are in warnings. If you find a defect, fix it and create the draft again while it is still a draft: once printed, the letter is out for good. 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. Either content OR blocks, never both. |
blocks | array<object | object | object | object | object | object | object | object | object | object | object | object> | optional | structured letter content as typed blocks (alternative to content, never both). |
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. |
recipientAddressInline | object | optional | |
presetName | string | optional | |
includeSignature | boolean | optional | Place the stored signature under the letter text. Off by default, same as on send. |
signatureId | string | optional | Use a specific stored signature instead 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 is refused with IDEMPOTENCY_CONFLICT, so you never believe a letter exists that does not. |
designId | string | optional | Use a 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, your reference, 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.