Brief versenden
order_sendVersendet einen Brief physisch per Post: prüft die Pflichtangaben des Absenders, die Empfängeradresse, den AVV und die Limits, erstellt die finale PDF und berechnet den Preis. Sieh dir den Brief vorher als Bild an: letter_create_draft und letter_preview liefern die gerenderten Seiten, und Satzprobleme wie ein zu langer Betreff zeigen sich erst dort. Ein Brief kommt entweder ueber letterId (ein bereits erstellter Entwurf) oder inline: dann ist der Text entweder content (Fliesstext) ODER blocks (strukturiert: Tabellen, Ueberschriften, Summenzeilen), genau eines von beiden. Kompaktes blocks-Beispiel: {"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}]}]} Volle Referenz inkl. styleDefs und Limits: MCP-Ressource frankki://blocks-guide. Eine echte OAuth-Verbindung landet immer in der Freigabewarteschlange. Die eingebettete Karte ist Vorschau und Freigabe. Nach ihrer Anzeige reicht im Chat eine kurze Bestätigung; PDF-Link und Brieftext gehören in reine Textansichten. Eine OAuth-Verbindung mit der ausdrücklich erteilten Berechtigung approval:self_approve darf über die Karte entscheiden. Danach fragst du den Fortschritt mit order_status ab. order_cancel storniert einen Brief vor dem Druck. order_fix_resubmit korrigiert einen vom Dienstleister abgelehnten Brief; auch dafür ist die ausdrückliche Selbstfreigabe nötig. Mit dryRun wird der Versand nur geprobt: kostenfrei, und der Brief bleibt liegen. dryRun ist die vollständige Probe genau dieses Briefes durch alle sechs Gates und liefert damit den genauesten Preis. Ein dryRun bleibt eine reine Probe: die zurückgegebene letterId ist eine Probe-Kennung und liefert in letter_get oder letter_preview NOT_FOUND. Für einen echten Entwurf nutze letter_create_draft. shipping_quote beantwortet dagegen die Frage, was ein Brief kosten würde, solange der Inhalt erst geplant ist; letter_preview zeigt einen blocks-Entwurf vorab als Bild, bevor er hier versendet wird. EN: Sends a letter physically by post: checks the sender's mandatory details, the recipient address, the AVV and the limits, creates the final PDF and calculates the price. Look at the letter as an image first: letter_create_draft and letter_preview return the rendered pages, and typesetting defects such as an over-long subject show up only there. A letter arrives either via letterId (an existing draft) or inline: then 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. A real OAuth connection always enters the approval queue. The embedded card is the preview and approval. Once it appears, a short chat confirmation is enough; PDF links and letter text belong in text-only views. An OAuth connection explicitly granted approval:self_approve may decide through the card. After that, poll progress with order_status. order_cancel cancels a letter before it goes to print. order_fix_resubmit corrects a letter rejected by the provider; it also requires explicit self-approval. With dryRun the send is only rehearsed: free of charge, and the letter stays put. dryRun is the full rehearsal of this specific letter through all six gates and therefore the highest-fidelity price. A dryRun stays a pure rehearsal: the returned letterId is a rehearsal handle and answers NOT_FOUND in letter_get or letter_preview. For a real draft, use letter_create_draft. shipping_quote instead answers what a letter would cost while the content is still only planned; letter_preview shows a blocks draft as an image before it is sent here.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Ohne Angabe wird die Farbe automatisch erkannt. EN: If omitted, colour is detected automatically. | |
| blocks | No | Strukturierter Briefinhalt als typisierte Bloecke (Alternative zu content, nie beides). Limits: 200 Bloecke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. EN: structured letter content as typed blocks (alternative to content, never both). Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Die vollstaendige Feldreferenz liegt in der MCP-Ressource frankki://blocks-guide. EN: every block needs type; read frankki://blocks-guide for the complete field reference. | |
| design | No | Exakter Briefdesign-Snapshot aus template_apply_with_merge_fields.composition.design. Hat Vorrang vor designId und verhindert, dass eine spaetere Designaenderung die freigegebene Vorlagenkomposition veraendert. EN: Exact letter-design snapshot from template_apply_with_merge_fields.composition.design. Takes precedence over designId and prevents later design edits from changing the released template composition. | |
| dryRun | No | ||
| content | No | Brieftext als Fliesstext. Entweder content ODER blocks, nie beides. EN: letter body as plain text. Either content OR blocks, never both. | |
| express | No | ||
| subject | No | ||
| auditTag | No | ||
| designId | No | Ein gespeichertes Briefdesign fuer diesen Versand verwenden. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand ueber letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Use a saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none. | |
| letterId | No | Bestehender Entwurf. Alternativ den Brief inline angeben. EN: Existing draft. Alternatively provide the letter inline. | |
| reasoning | No | ||
| reference | No | Werte fuer diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie fuellen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode. | |
| styleDefs | No | Benannte Stile fuer das ganze Dokument (max. 24). Bloecke referenzieren sie ueber style. EN: named document styles (max 24); blocks reference them via style. Vollstaendige Stilfelder: frankki://blocks-guide. EN: complete style fields: frankki://blocks-guide. | |
| presetName | No | ||
| templateId | No | ||
| scheduledAt | No | ||
| signatureId | No | ||
| approvalMode | No | Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. Wichtig: auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief spaeter nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurueck und es wird nichts angelegt. Willst du nur einen Entwurf ohne Wallet-Deckung, nutze letter_create_draft. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. Note: both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. For a plain draft with no wallet cover, use letter_create_draft. | |
| deliveryType | No | Standard standard. EN: Defaults to standard. | |
| letterheadId | No | Bestimmter Briefkopf fuer diesen Versand. Ohne Angabe wird der Standard-Briefkopf verwendet. EN: A specific letterhead for this send. If omitted, the default letterhead is used. | |
| maxCostEuros | No | Maximalbetrag in Euro. Liegt der Preis darueber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted. | |
| priceVersion | No | Optional: die priceVersion aus einem vorherigen shipping_quote. Weicht der Preis beim Versand davon ab, wird mit PRICE_CHANGED abgebrochen, bevor etwas berechnet wird. EN: Optional: the priceVersion from an earlier shipping_quote. If the price at send time differs, the call is aborted with PRICE_CHANGED before anything is charged. | |
| recipientZip | No | ||
| clientOrderId | No | Idempotenzschluessel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format noetig). Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert. EN: Idempotency key: any string (1-200 characters, e.g. 'mahnung-kunde42-2026-07-20'; no UUID format required). A repeat call with the same value returns the same order instead of sending a second time. The 'approval:' namespace is reserved. | |
| recipientCity | No | ||
| recipientName | No | ||
| coverTemplateId | No | Anschreiben für eine eigenständige Formularvorlage. EN: Cover letter for a standalone form template. | |
| mandantennummer | No | ||
| recipientStreet | No | ||
| senderAddressId | No | ||
| senderProfileId | No | ||
| includeSignature | No | ||
| recipientCompany | No | ||
| recipientCountry | No | ISO-3166-alpha-2, Standard DE. EN: ISO 3166-1 alpha-2, defaults to DE. | |
| letterheadEnabled | No | Auf false setzen, um den Briefkopf fuer diesen einen Versand zu unterdruecken. EN: Set to false to suppress the letterhead for this one send. | |
| templateVersionId | No | Exakte freigegebene Vorlagenversion. Nur gemeinsam mit templateId; der Server rendert sie mit templateMergeValues neu und ignoriert mitgesendeten Betreff/Inhalt. EN: Exact released template version. Only with templateId; the server rerenders it with templateMergeValues and ignores caller-supplied subject/content. | |
| templateMergeValues | No | Merge-Werte fuer die exakte Vorlagenversion. EN: Merge values for the exact template version. | |
| quotedUnitPriceCents | No | Optional: der Stueckpreis in Cent aus einem vorherigen shipping_quote (unitPriceCents). Ist er gesetzt, entscheidet er den PRICE_CHANGED-Abgleich und liefert den alten Preis im Fehler mit. EN: Optional: the unit price in cents from an earlier shipping_quote (unitPriceCents). If set, it decides the PRICE_CHANGED comparison and returns the old price in the error. | |
| recipientHouseNumber | No | ||
| coverTemplateVersionId | No | Exakte freigegebene Version des Anschreibens. EN: Exact released version of the cover letter. |