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 über letterId (ein bereits erstellter Entwurf) oder inline: dann ist der Text entweder content (Fließtext) ODER blocks (strukturiert: Tabellen, Überschriften, 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. Bei einer Mahnung, Kündigung, Mieterhöhung oder einem anderen Brief mit Frist frag, ob der Mensch ein Einschreiben möchte, und nenne dessen Preis aus shipping_quote. Rechtliche Fragen beantwortet eine Anwältin oder ein Anwalt; du nennst Versandarten und Preise. 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. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, ask whether the person wants Einschreiben and state its price from shipping_quote. Leave legal advice to a lawyer; you name the delivery options and prices. 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 Blöcke (Alternative zu content, nie beides). Limits: 200 Blöcke, 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 spätere Designänderung die freigegebene Vorlagenkomposition verändert. 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 Fließtext. 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 für diesen Versand verwenden. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über 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 für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen 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 für das ganze Dokument (max. 24). Blöcke referenzieren sie über 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. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Wichtig: auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück 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. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. 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 für 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 darüber, 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 | Idempotenzschlüssel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format nötig). 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 für diesen einen Versand zu unterdrücken. 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 für die exakte Vorlagenversion. EN: Merge values for the exact template version. | |
| quotedUnitPriceCents | No | Optional: der Stückpreis 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. |