Tool reference
This list is generated at build time directly from the server tool registry, no field is hand-maintained. A registered, enabled tool appears with real fields, a registered-but-dark tool shows "Coming soon", an unregistered tool never appears at all. The wire conventions (ISO-8601, cent amounts, clientOrderId, dryRun) are stated once in the Conventions panel, here only as a short per-tool pointer.
apiVersion v1 · schemaRevision 2 · 64 tools
Every tool call can also return one of these transport codes, listed once here: UNAUTHORIZED, FORBIDDEN_SCOPE, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR
Read
Health/echo probe - verifies the partner token and the chain end to end, and reports under setup which prerequisites for a real send are already met (sender profile, data processing agreement, balance, sandbox, approval) and what the next step is. With checkRender: true it additionally checks whether rendering currently works at all (preview, thumbnail). Call it before building a template you will need to look at.
Field Type checkRender boolean Optional Additionally probes the render path (composer + rasterizer). Defaults to false. profile_getScope: profile:readReturns an overview of the partner profile: default sender address, stored signature and letterhead, saved presets, a short wallet summary and the partner's current pricing (standard price or volume tier, including the next tier threshold).
No input fields besides reasoning.
wallet_balanceScope: wallet:readReturns the current wallet status: balance, daily cap for letters and costs, and the next reset time. If the balance is short of the planned send, call wallet_topup_link and give the human the top-up link.
No input fields besides reasoning.
sender_profile_listScope: sender_profile:readLists all of the partner's sender profiles with their legal form and whether the mandatory details are complete.
No input fields besides reasoning.
sender_profile_getScope: sender_profile:readReturns a single sender profile with all mandatory details, bank account and disclaimer.
Field Type profileId string (uuid) Required Error codes: NOT_FOUND
mandant_getScope: mandant:readReturns a client (Mandant) with addresses, category, case handler, monthly cap, monthly budget used, retention period and the letter count of the last 12 months.
Field Type mandantId string Optional mandantennummer string Optional Error codes: NOT_FOUND
mandant_listScope: mandant:readLists the partner's clients (Mandanten), optionally filtered by search term, category or tag.
Field Type searchQuery string Optional kategorieFilter string Optional tagFilter string Optional since string (date-time) Optional Only clients created since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. mandant_searchScope: mandant:readSearches clients (Mandanten) by client number, name, tags or case handler and names the matching column for each hit. Next step with the matched mandantennummer: document_create turns it into an invoice, dunning letter, payment reminder or credit note, mandant_get returns the full record, letter_create_draft writes a normal letter.
Field Type query string Required since string (date-time) Optional Only clients created since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. template_listScope: template:readList templates, template list: lists the available letter templates for occasions such as cancellation, invoice, payment reminder, quote, contract and letters to public authorities, with category, version and their placeholders (merge fields). The exact technical tool name is template_list; if your client defers tools, search for template_list. By default it returns released templates; with statusFilter and the template:write scope also open drafts. Every entry says with curated: true whether it is a curated FrankKi standard template (the library to copy from), and with hasBlocks: true whether it carries a structured layout with tables and totals instead of plain text. Next step: template_get returns one template in full (for a block template including blocksTemplate and styleDefs to copy and modify), template_apply_with_merge_fields fills it with your values.
Field Type kategorieFilter string Optional statusFilter released | draft | all Optional released (default) shows every released template. Standalone form templates carry sendable:false and require a cover letter when applied. draft shows only open drafts, all shows both. draft and all additionally require the template:write scope. limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. template_getScope: template:readReturns a single template with subject and content template, the merge fields and the recommended approval default. A block template additionally returns blocksTemplate and styleDefs, so you can copy it, modify it and store it as your own draft with template_save. That is exactly how the crafting loop starts: template_get on a curated standard template (template_list marks them with curated: true), modify blocksTemplate, look at it with letter_preview, refine, then template_save, check the stored version with template_preview and finally template_release. With versionId and the template:write scope a specific draft version can be read too. Next step: template_apply_with_merge_fields fills the placeholders with your values.
Field Type templateId string (uuid) Required versionId string (uuid) Optional Optional: read one specific version, including a draft. Additionally requires the template:write scope. If omitted, the released version is read. Error codes: NOT_FOUND
letter_getScope: letter:readReturns one of the partner's letters together with its order and a download URL for the PDF valid for 24 hours.
Field Type letterId string (uuid) Optional orderId string (uuid) Optional letter_listScope: letter:readLists the partner's letters with optional filters by recipient name, subject, status and time.
Field Type recipientNameContains string Optional subjectContains string Optional statusFilter string Optional since string (date-time) Optional limit integer Optional offset integer Optional sender_profile_validateScope: sender_profile:readChecks whether a sender profile (by profileId) or a proposed field set contains all mandatory details for its legal form. Provide exactly one form: profileId OR rechtsform + proposedFields. proposedFields is an object; a JSON-encoded object string is also accepted. Returns valid, missingFields and soft hints. Reports a gap as a result and keeps running.
No input fields besides reasoning.
analytics_summaryScope: analytics:readReturns the partner account's aggregated metrics: letters per month, cost per mandant for rebilling, transit times to delivery, failure rates, and spend against configured limits. Amounts are net cost in cents.
Field Type metric overview | letters_per_month | cost_per_mandant | delivery_times | failure_rates | spend_vs_caps Optional Which report. overview (default) summarises the last three months. months integer Optional Trend length for letters_per_month and failure_rates, 1 to 24, default 12. since string Optional Range start, for example 2026-01-01. Default: last 90 days. until string Optional Range end, default now. topN integer Optional Number of mandants in cost_per_mandant, 1 to 50, default 10. address_listScope: address:readLists the addresses in the partner address book. Optionally filtered by name, city or client.
Field Type searchQuery string Optional limit integer Optional address_validateScope: address:readValidates an address using country-specific rules and reports hard failures as ADDRESS_INVALID. A check only, the address book is left untouched; to create or change an address use address_upsert.
Field Type name string Required company string Optional street string Required houseNumber string Optional pobox string Optional zip string Optional city string Required country string Optional ISO 3166-1 alpha-2, defaults to DE. mandantennummer string Optional addressType recipient | sender | billing Optional isDefault boolean Optional Error codes: ADDRESS_INVALID
template_apply_with_merge_fieldsScope: template:readFills a saved template and returns subject and content or a complete cover-form package. For a block template the finished blocks are returned instead of content. Letterhead and brand are selected separately at preview or send time. A standalone form template with sendable:false and releaseBlocker:null needs coverTemplateId from a directly addressable letter template; a saved link is only the optional default. Then pass templateId, templateVersionId, coverTemplateId, coverTemplateVersionId and the original templateMergeValues unchanged to order_send. Pass package sections on exactly as they come back. If a required value is missing, the tool returns MERGE_FIELDS_MISSING and lists the missing or invalid fields.
Field Type templateId string (uuid) Required The template ID from template_list / template_get. templateVersionId string (uuid) Optional Exact released or superseded template version. If omitted, the currently released version is used. coverTemplateId string (uuid) Optional Optional cover letter for a standalone form template. Required when applying a form that has no saved link. coverTemplateVersionId string (uuid) Optional Optional exact released version of the selected cover letter. mergeValues object Optional Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. The merge field's type applies: date expects ISO YYYY-MM-DD, currency integer cents, number a number, rows a list of row objects keyed by the bound table's column keys. language de | en Optional Language for money and date formatting. Defaults to de. mandantennummer string Optional Optional client reference (context only). Error codes: NOT_FOUND
shipping_quoteScope: letter:readDetermines the price, letter format, shipping method and estimated delivery time for a planned letter, before it is sent. This is the estimate for when the letter is still only planned: you only supply page count, country and delivery type. Once the letter exists, order_send performs the actual send (and order_send with dryRun:true gives the more precise price for that specific letter). The price is per letter and already includes the partner's volume tier where one applies (field tierId). For the volume tiers themselves, call pricing_tiers.
Field Type pageCount integer Required Page count for a general estimate. With letterId, FrankKi uses the stored page count and ignores this value. color boolean Required Colour assumption for a general estimate. With letterId, FrankKi detects colour from the stored preview and ignores this value. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Required Registered-mail availability depends on the destination and its current catalog, not a Germany-only rule. The codes einschreiben_einwurf and einschreiben_uebergabe are German products; Switzerland uses ch_einschreiben. For other destinations, use only methods returned in availableDeliveryTypes by a standard shipping_quote for that country, then quote the chosen code. A rejected country/method pair does not establish availability in other countries. A catalog snapshot with no registered method does not prove that the postal service never offers one. Tracked mail is not registered mail. Never substitute standard or tracked delivery when registered mail was requested without the user's agreement. A carrier-issued proof-of-posting PDF is not promised. express boolean Optional country string, max 2 chars Optional ISO 3166-1 alpha-2, defaults to DE. letterId string (uuid) Optional Optional: the letterId of an existing draft. Page count and colour then come from the stored preview; for the final price including attachments, use order_send with dryRun:true. pricing_tiersScope: letter:readReturns FrankKi's volume tiers (bulk discounts): from which monthly quantity which example price per letter applies. Use this when someone asks about bulk discounts, volume pricing or enterprise pricing. The example prices are for a one-page black and white standard letter within Germany; the real per-letter price also depends on page count, color, delivery type and destination country (use shipping_quote for that).
No input fields besides reasoning.
order_statusScope: order:readReturns the current status of an order including a chronological German tracking history, the tracking number (registered mail only), the estimated delivery and whether the letter can still be cancelled. On status awaiting_partner_fix the letter is waiting for a correction: call order_fix_resubmit. While cancellable is true, order_cancel can still stop the send.
Field Type orderId string (uuid) Required Error codes: NOT_FOUND
order_einlieferungsbelegScope: order:readReturns the proof of posting (Einlieferungsbeleg) for a sent order: a download URL for the receipt PDF valid for 90 days, the postmark, the mail provider and the verified record from the GoBD archive.
Field Type orderId string (uuid) Required Error codes: NOT_FOUND
approval_listScope: approval:readLists your account's approvals, newest first, with a time-limited PDF preview, the cost, the reason and the deadlines. Only the pending approvals by default. You then decide on one of the returned approvalIds with approval_decide.
Field Type status pending | approved | rejected | expired Optional Default pending. since string (date-time) Optional Only approvals submitted since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. setup_fix_linkScope: profile:readHands one item over to the human in a browser: top up the balance, sign the data processing agreement or complete the sender profile. Returns the matching page plus a card that visibly keeps the letter draft and notices by itself when the human is back. Payment always happens in the browser.
Field Type gap wallet | avv | senderProfile Required Which item is handed over: wallet (balance), avv (consent) or senderProfile (sender profile). wallet_topup_linkScope: wallet:readCreates a Stripe checkout link to top up your wallet balance. Card data stays with Stripe; the balance is credited once the payment completes.
Field Type amountEuros number Required Top-up amount in euros, between 10 and 500. requestNonce string, max 200 chars Optional Optional stable retry key. On a retry send the same value to get the same checkout link instead of a second one. Error codes: INSUFFICIENT_FUNDS
template_diff_checkScope: template:readCompares your final letter with the template and shows you where you deviated. For a block template pass finalBlocks instead of finalContent; the texts are compared in reading order. Free and read-only.
Field Type templateId string (uuid) Required The template ID from template_list / template_get. versionId string (uuid) Optional Optional: a specific version, otherwise the released one. finalSubject string Required Your final subject line. finalContent string Optional Your final letter text. For a block letter use finalBlocks instead. finalBlocks Array<object> Optional Your final blocks when the letter is structured. The texts are compared in reading order. mergeFields object Optional Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. Error codes: NOT_FOUND
letter_design_listScope: letter_design:writeLists the partner's saved letterheads (letter designs) with the full design JSON. A design is referenced by name or id when sending and carries every kind of mail: cancellation, invoice, payment reminder, quote, contract and letters to public authorities.
Field Type includeArchived boolean Optional Include archived (deleted) designs too. Defaults to false. letter_design_previewScope: letter_design:writeRenders a saved or inline schemaVersion 1 or 2 letter design through the same resolution and composer as an actual send. It uses real partner sender data with a fictional recipient and sample body. Returns one inline PNG page by default; page 2 only for continuationHeader. With sampleVariant empty you see the stationery on its own: header and footer are typeset for real, the text area stays open, and this is the very picture the dashboard shows. It shows in advance how a cancellation, invoice, payment reminder, quote, contract or letter to a public authority looks on this stationery. The run stays free of charge and the letter stays a draft.
Field Type designId string (uuid) Optional design unknown Optional reference object Optional sampleSubject string, max 200 chars Optional sampleContent string, max 4000 chars Optional sampleVariant typical | empty Optional typical shows a full example page for judging readability and rhythm. empty shows the stationery on its own: header and footer are typeset for real and the text area stays open. Your own sampleContent takes precedence over both. pages integer Optional The default is page 1 only. Page 2 is returned only for continuationHeader. resolution thumb | full Optional Error codes: DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
letter_design_list_presetsScope: letter_design:writeReturns the owner-approved native-v2 letterheads as safe starting points for cancellations, invoices, payment reminders, quotes, contracts and letters to public authorities. It grows with every curated design that passes review. The plain list stays text-only and therefore cheap; presetId renders exactly one real-composer preview with an inline PNG.
Field Type presetId string Optional Optional: load one preset with its rendered preview. Without presetId the list stays image-free and cheap. pages integer Optional resolution thumb | full Optional brand_kit_getScope: profile:readReads the saved brand values for the user-facing result letterhead and brand. Returns logo references, colours and font for further work with letter_design_preview and letter_design_save.
No input fields besides reasoning.
signature_listScope: profile:readLists the signatures stored in the partner profile with a short-lived preview URL (valid for 24 hours).
No input fields besides reasoning.
letterhead_listScope: profile:readLists the letterheads stored in the partner profile with a short-lived preview URL (valid for 24 hours).
No input fields besides reasoning.
address_search_companyScope: address:readSearches companies and public authorities in the directory and returns the matching mailing address including an authority PO box.
Field Type query string Required country string Optional letter_searchScope: letter:readFull-text searches the partner's letters across subject, recipient name and letter content.
Field Type query string Required since string (date-time) Optional Only letters modified since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. archive_exportScope: archive:readSchedules an archive export (GoBD CSV, DATEV, PDF bundle or client allocation) for a date range and returns a job ID to query its status.
Field Type since string (date-time) Required until string (date-time) Required format gobd_csv | datev_export | pdf_bundle | mandant_allocation_pdf | mandant_allocation_csv Required target string Optional mandantennummerFilter string Optional senderProfileFilter string (uuid) Optional notifyEmail string (email) Optional Error codes: NOT_FOUND
archive_export_statusScope: archive:readReturns the status of an archive export job and, once complete, a download URL valid for 90 days.
Field Type jobId string (uuid) Required Error codes: NOT_FOUND
letter_previewScope: order:sendPreview letter and draft as images, render form preview: composes like a real send and returns inline PNGs, PDF link, page count, cost and designRender with the actual documentMode, rendered letter chrome and bodyStartMm. The preview stays free of charge and the letter stays put. Use letterId or inline content OR blocks. With letterId, the embedded card is the human preview. Once it appears, a short chat confirmation is enough; PDF links and letter text belong in text-only views. An unsaved design may be supplied directly and applies to this one preview only. IMPORTANT FOR FORMS: always preview self-declarations, questionnaires, certificates and other standalone forms first with design: { "schemaVersion": 1, "documentMode": "form" }; that is what drops recipient block, date and subject and starts content at 27 mm. Full reference: frankki://blocks-guide. For a rebuild, compare every PNG page against the original. If page count or major geometry differs, correct blocks or design and preview again; save once both match. Once matched, save with template_save, then use template_release.
Field Type letterId string (uuid) Optional Preview a stored draft. Alternatively provide the letter inline. subject string, max 200 chars Optional Subject. Required without a letterId. content string, max 30000 chars Optional letter body as plain text. Either content OR blocks, never both. blocks Array<unknown> (min 1, max 200) 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 designId string (uuid) Optional Use a saved letter design for this preview. design object Optional Unsaved letter design for this preview only. Takes precedence over designId and creates no account entry. Set documentMode: "form" for standalone forms. reference object Optional Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and barcode in the preview. senderProfileId string (uuid) Optional pages integer Optional How many pages come back as images. Default 3, maximum 8. The PDF link always contains every page. resolution thumb | full Optional thumb (96 dpi, default, fast and small) or full (150 dpi, for checking details). template_previewScope: template:readRenders a STORED template with sample values and returns inline PNGs, PDF link and designRender. designId or an unsaved design selects the stationery; set documentMode: "form" for standalone forms. The preview stays free of charge and is purely for looking at. Use letter_preview for a blocks layout that is still in the making. Call template_save to persist a finished version. If the client unloaded that tool, search for the exact technical name template_save.
Field Type templateId string (uuid) Required The template ID from template_list / template_get. versionId string (uuid) Optional Exact template version to inspect. If omitted, the released version is used, then the newest draft. designId string (uuid) Optional Saved letter design for this template preview. designVersionId string (uuid) Optional Exact immutable letterhead version for this preview. design object Optional Unsaved letter design for this preview only. Set documentMode: "form" for forms. pages integer Optional How many pages come back as images. Default 1, maximum 3. Error codes: NOT_FOUND
document_listScope: letter:readLists the documents you created (invoice, payment reminder, dunning letter, credit note), newest first, filtered by type, client, recipient or referenced document. Next step: document_get returns the full payload, document_create creates a follow-up document via references.
Field Type documentType rechnung | zahlungserinnerung | mahnung | gutschrift Optional mandantennummer string Optional recipientQuery string Optional free text over the recipient name, company or city. referencesDocumentId string (uuid) Optional only documents referring to this FrankKi document (for example every dunning letter for one invoice). referencesNumber string Optional since string (date-time) Optional limit integer Optional default 20, maximum 100. offset integer Optional offset for pagination. Default 0. document_getScope: letter:readReturns one document with its full payload (line items, totals, VAT rates, reference) plus the letterId and orderId of the letter it lives in. The field referencePrefill carries the ready-made references block for a follow-up document: paste it unchanged into document.references of a document_create for a dunning letter, payment reminder or credit note. Under exports FrankKi returns signed download links for sent invoices and credit notes: zugferdPdfUrl is a PDF/A-3 with embedded EN 16931 XML (ZUGFeRD), xrechnungXmlUrl the pure XRechnung XML. Both are download-only; transmitting an e-invoice to a portal stays with you. When an export is missing the slot names the reason: DOCUMENT_EXPORT_NOT_READY means try again later (the send or the activation is still pending), DOCUMENT_EXPORT_NOT_SUPPORTED means permanently (the export covers invoices and credit notes; for a dunning letter or payment reminder use the invoice they refer to). Next step: order_status tracks the send, document_create creates a dunning letter or credit note via references.
Field Type documentId string (uuid) Required
Action
sender_profile_upsertScope: sender_profile:writeno dryRunCreates or edits a sender profile: legal form, mandatory details, optionally bank details, disclaimer and default letterhead. An incomplete profile is saved and reports its missing fields back, so you can complete it step by step. Sending works once they are complete.
Field Type id string Optional Id of an existing profile to edit. Omitting creates a new one. rechtsform string Required The sender's legal form. It determines the required mandatory details. pflichtangaben object Required Mandatory details as an object. sender_profile_validate names the fields required per legal form. bankverbindung object Optional Optional bank details, independent of completeness. disclaimer string Optional Optional disclaimer or footer, independent of completeness. displayName string Optional Optional display name in lists. isDefault boolean Optional true makes this the default sender. The first profile created becomes default. defaultDesignId stringnull Optional Letterhead for letters naming none. Omitting keeps the value, null clears it. address_upsertScope: address:writeno dryRunCreates or updates an address in the partner address book. Validates the address using country-specific rules.
Field Type addressId string (uuid) Optional name string Required company string Optional street string Required houseNumber string Optional pobox string Optional zip string Optional city string Required country string Optional ISO 3166-1 alpha-2, defaults to DE. mandantennummer string Optional addressType recipient | sender | billing Optional isDefault boolean Optional Error codes: ADDRESS_INVALID
Creates 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. The embedded card is the human preview. Once it appears, a short chat confirmation is enough; PDF links and letter text belong in text-only views. 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.
Field Type subject string, max 200 chars Required content string, max 30000 chars Optional letter body as plain text. Either content OR blocks, never both. blocks Array<unknown> (min 1, max 200) 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 (uuid) Optional senderProfileId string (uuid) 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 (uuid) 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 (uuid) 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. attachment_upload_pdfScope: order:sendno dryRunUploads a PDF as an attachment to a partner letter. Before saving, it checks the file size (max. 50 MB) and the merged page count (max. 30 pages including the letter and other attachments).
Field Type letterId string (uuid) Required pdfUrl string Optional Public URL of the PDF (alternative to pdfBase64). pdfBase64 string Optional PDF as Base64 (alternative to pdfUrl). title string Optional position integer Optional attachment_upload_imageScope: order:sendno dryRunUploads an image (PNG/JPEG) as an attachment to a partner letter. The image is scaled to an A4 PDF page server-side (optionally rotated) and stored like a PDF. Before saving, it checks the merged page count (max. 30 pages). EXIF orientation is applied to the pixels automatically, so a phone photo is upright by itself. rotation applies on top of that: leave it at 0 unless you deliberately want to turn the image further.
Field Type letterId string (uuid) Required imageUrl string Optional Public URL of the image (alternative to imageBase64). imageBase64 string Optional Image as Base64 (alternative to imageUrl). rotation 0 | 90 | 180 | 270 Optional Additional clockwise rotation in degrees. The image's EXIF orientation is already baked into the pixels automatically, so the image is upright on its own. This value turns it a second time on top of that. For a phone photo, 0 is therefore the correct value. title string Optional position integer Optional 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.
Field Type letterId string (uuid) Optional Existing draft. Alternatively provide the letter inline. subject string, max 200 chars Optional content string, max 30000 chars Optional letter body as plain text. Either content OR blocks, never both. blocks Array<unknown> (min 1, max 200) 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. recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional ISO 3166-1 alpha-2, defaults to DE. priceVersion string Optional 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. quotedUnitPriceCents integer Optional 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. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional Defaults to standard. express boolean Optional color boolean Optional If omitted, colour is detected automatically. includeSignature boolean Optional signatureId string (uuid) Optional letterheadId string (uuid) Optional A specific letterhead for this send. If omitted, the default letterhead is used. letterheadEnabled boolean Optional Set to false to suppress the letterhead for this one send. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional clientOrderId string, max 200 chars Optional 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. scheduledAt string (date-time) Optional approvalMode auto | draft | review Optional 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. maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional templateId string (uuid) Optional templateVersionId string (uuid) Optional Exact released template version. Only with templateId; the server rerenders it with templateMergeValues and ignores caller-supplied subject/content. templateMergeValues object Optional Merge values for the exact template version. coverTemplateId string (uuid) Optional Cover letter for a standalone form template. coverTemplateVersionId string (uuid) Optional Exact released version of the cover letter. designId string (uuid) Optional 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. design object Optional 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. reference object Optional Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode. dryRun boolean Optional Idempotency key: clientOrderId (see Conventions).
Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, PDF_LETTER_UNSUPPORTED, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
Submits a letter for human approval: checks mandatory details, recipient, data processing agreement and limits, creates the final PDF, calculates the price, reserves the cost and adds an approval to the 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. With approval:self_approve, the card shows Approve and Reject. In every other case it opens the signed-in portal. With dryRun, the balance and queue remain untouched.
Field Type letterId string (uuid) Optional Existing draft. Alternatively provide the letter inline. subject string, max 200 chars Optional content string, max 30000 chars Optional recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional ISO 3166-1 alpha-2, defaults to DE. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional Defaults to standard. express boolean Optional color boolean Optional If omitted, colour is detected automatically. includeSignature boolean Optional signatureId string (uuid) Optional senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional clientOrderId string Optional Idempotency key. A repeat call with the same value returns the same approval instead of submitting a second time. The 'approval:' prefix is reserved. scheduledAt string (date-time) Optional approvalMode auto | draft | review Optional maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional templateId string (uuid) Optional reason string, max 500 chars Optional Short reason for the approval, shown to the reviewer on the card. requesterContext string, max 500 chars Optional Additional context about the submitter or the occasion. dryRun boolean Optional Idempotency key: clientOrderId (see Conventions).
Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, IDEMPOTENCY_CONFLICT
Approves or rejects a pending approval. 'approve' is allowed only when this OAuth connection was explicitly granted the additional approval:self_approve scope. When that scope is absent, the human opens the returned approvalUrl and decides in the signed-in portal. approval:decide is also required. An agent approval dispatches after 10 minutes and can be stopped with order_cancel until then.
Field Type approvalId string (uuid) Required decision approve | reject Required comment string, max 1000 chars Optional clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
Error codes: APPROVAL_ALREADY_DECIDED, NOT_FOUND
order_cancelScope: order:sendno dryRunCancels a letter and credits the amount to your wallet (closed loop, credited to the wallet rather than the card). With orderId it cancels an existing order within the cancellation window; if the letter is already printing the call is cleanly rejected. With approvalId it stops a chat-approved send within its 10-minute grace window before it is even sent (the human says 'stop').
Field Type orderId string (uuid) Optional The order to cancel. approvalId string (uuid) Optional Instead of orderId: stop a chat-approved send within its 10-minute grace window before it is sent (the human says 'stop'). reason string, max 500 chars Optional Optional cancellation reason. Error codes: NOT_FOUND
template_saveScope: template:writeno dryRunSave template, save template version, create template draft: writes a template as a DRAFT. Set documentKind to letter or form. Letterhead and brand remain an external layer resolved at preview or send time and stay outside the template. designId remains only as a deprecated hint for inferring document kind; explicit documentKind wins. A form may be saved independently. coverTemplateId may pin a cover-template version for a package. Leave templateId out and a new template is created; with templateId a new draft version is created. The draft is usable only after release; the response includes the review link. If the tool is missing, search for the exact technical name template_save. The template body is either contentTemplate (plain text) OR blocksTemplate (structured: tables, headings, totals lines), exactly one of the two. Merge fields are typed (text, date, number, currency, rows); a table block binds a rows list via rowsFrom. The fastest start is copying a standard template with template_get and modifying it. Before saving: render with letter_preview and compare page by page. Save once page count and major geometry match the original. Preview standalone forms with a design using documentMode "form" first.
Field Type templateId string (uuid) Optional Existing template: a NEW draft version is created. If omitted, a new template is created. name string Required Name of the template. kategorie stringnull Optional Subject category, e.g. kuendigung (termination). subjectTemplate string Required Subject template, may contain {{placeholders}}. contentTemplate string Optional Content template as plain text, may contain {{placeholders}}. Either contentTemplate OR blocksTemplate. blocksTemplate Array<unknown> (min 1, max 200) Optional Structured content template (tables, headings, totals lines). Text fields may contain {{placeholders}}; a table block can bind a rows merge field via rowsFrom: "<key>" and receives its rows on apply. Either contentTemplate OR blocksTemplate. Full reference: MCP resource frankki://blocks-guide. styleDefs object Optional Named styles of the block template. Only together with blocksTemplate. mergeFields Array<object> (max 100) Optional The placeholders of the template. approvalModeRecommended auto | review | draft | Optional Recommended approval mode for letters from this template. documentKind letter | form Optional Immutable document kind of the template version. letter is directly addressable; form requires a cover letter. designId string (uuid) Optional Deprecated authoring hint used to infer documentKind. The design is not stored on the template. Explicit documentKind wins. clearDesign boolean Optional Deprecated compatibility authoring hint. New template versions have no design binding. coverTemplateId string (uuid) Optional Cover template for a form without a recipient block. Saving pins its exact current released version. clearCoverTemplate boolean Optional Removes the inherited cover-template pin. Without coverTemplateId and clearCoverTemplate, a new version inherits the previous pin. Error codes: NOT_FOUND, TEMPLATE_SLUG_CONFLICT
template_releaseScope: template:writeno dryRunReleases a draft version so it can be sent. This is the last step of the crafting chain (template_get, modify, letter_preview, template_save, template_preview, template_release). IMPORTANT: template_preview shows the human an approval card with a Release button. While that card is open the release belongs to the human. Only call template_release when the person explicitly asks you to, and always say plainly that you released it yourself. Via MCP this is only possible when your account has exactly one active user. With several users a human releases it in the dashboard (four-eyes principle) and the response contains the link. After that: template_apply_with_merge_fields fills the template with values, letter_create_draft or order_send sends the result.
Field Type templateId string (uuid) Required versionId string (uuid) Required The draft version to release. Error codes: NOT_FOUND, TEMPLATE_VERSION_NOT_DRAFT, TEMPLATE_FOUR_EYES_REQUIRED
template_archiveScope: template:writeno dryRunArchives a template. It disappears from the lists and from sending but is kept. The content stays fully preserved and calling it again is harmless.
Field Type templateId string (uuid) Required Error codes: NOT_FOUND
template_draft_discardScope: template:writeno dryRunDiscards a draft version while it is still waiting for its release. Released and superseded versions stay untouchable and fully preserved. Calling it again is harmless.
Field Type templateId string (uuid) Optional Optional. Additionally pins the version to this template. versionId string (uuid) Required The draft version to discard. Error codes: NOT_FOUND, TEMPLATE_VERSION_IMMUTABLE
preset_saveScope: preset:writeno dryRunSaves a named preset (configuration bundle) in the partner profile. The name is unique per partner. Limits inside the preset are stored as-is and serve as a note. Enforcement runs exclusively on the account and sub-wallet limits set in the web app.
Field Type name string Required Unique name of the preset (per partner). preset object Required The configuration bundle (sender/signature/letterhead, shipping, labelling, approval, scheduling, limits, auditTagPrefix). signature_uploadScope: signature:writeno dryRunUploads a signature as PNG and stores it in the partner profile. On sending, the signature is inserted below your letter body. Only PNG is supported.
Field Type pngBase64 string Required The signature as PNG (Base64). widthMm number Optional Desired width in mm (optional). displayName string Optional Display name of the signature (optional). letterhead_uploadScope: letterhead:writeno dryRunUploads a letterhead as PNG or PDF and stores it in the partner profile. The source is either fileUrl (preferred) or fileBase64, exactly one of the two. PNG is printed on the page; a PDF letterhead is only filed for now, printing stays PNG-only (rendered=false). When rebuilding an existing letter: the logo and title block at the top of the page belong here (then letter_design_save); the letter body stays reserved for blocks.
Field Type fileBase64 string Optional The letterhead as PNG or PDF (Base64), alternative to fileUrl. fileUrl string Optional Public http(s) URL of the letterhead (PNG or PDF), alternative to fileBase64. Prefer this variant: base64 wastes context and encourages heavy colour reduction, which degrades the printed letterhead. Maximum 20 MB. widthMm number Optional Width in mm (optional). heightMm number Optional Height in mm (optional). placement header | footer | full Optional Placement on the page. displayName string Optional Display name of the letterhead (optional). letter_design_saveScope: letter_design:writeno dryRunSaves a reusable schemaVersion 1 or 2 letterhead (letter design) in the partner profile and returns its designId and stored-source hash. The same stationery then carries every kind of mail: cancellation, invoice, payment reminder, quote, contract and letters to public authorities. If the client unloaded the tool, search for letter_design_save. The design is fully validated and checked against postal clear zones before it is stored.
Field Type name string, max 120 chars Required Unique name of the letter design. design unknown Required designId string (uuid) Optional brandingOwnershipConfirmed boolean Optional Required as true when creating or changing a branding asset reference. Unchanged iterative saves need no renewed confirmation. Error codes: DESIGN_ZONE_VIOLATION
letter_design_deleteScope: letter_design:writeno dryRunArchives (deletes) a saved letterhead (letter design). New sends then run on the remaining letterheads, whether cancellation, invoice, payment reminder, quote, contract or letter to a public authority; already-sent letters keep their original for auditability.
Field Type designId string (uuid) Required The letter design to delete. Error codes: NOT_FOUND
brand_kit_saveScope: letter_design:writeno dryRunSaves logo references, colours and font for the user-facing result letterhead and brand. brandingOwnershipConfirmed must be true and confirms the usage rights for the supplied brand assets. The response includes the saved state and review link.
Field Type brandKit object Required brandingOwnershipConfirmed boolean Required Confirms usage rights for the logo and custom font. Must be true. brand_import_from_websiteScope: letter_design:writeno dryRunReads a public company website and proposes a letterhead design from it: brand colours, a mapped house typeface, logo candidates and company details from the imprint. Found logos are stored as design assets in the account so you can use them right away. The result is a proposal to review with the customer; the brand is adopted by a following brand_kit_save call carrying brandingOwnershipConfirmed. Search technically for brand_import_from_website.
Field Type websiteUrl string, max 2048 chars Required Public company website address. maxLogoCandidates integer Optional How many logo candidates get downloaded and stored. Default 3. letter_scheduleScope: letter:scheduledryRun availableSchedules an existing draft for a later time (fixed date, relative delay or recurring via cron). All checks and the price are determined immediately and the cost is reserved. A real OAuth connection creates an approval first. 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 with approval:self_approve may decide through the card. Approval creates the schedule, and the actual send runs at the planned time through the same send pipeline.
Field Type letterId string (uuid) Required Existing draft to be sent on schedule. mode at | in | cron Required at = fixed time, in = relative delay, cron = recurring. sendAt string (date-time) Optional Time for mode='at' (ISO 8601, Berlin time if no offset). delay string Optional Delay for mode='in': '2d', '1w', '3h', 'next-business-day', 'next-monday', 'end-of-month'. cronExpression string Optional 5-field cron for mode='cron': 'min hour day month weekday'. endDate string (date-time) Optional End date for a cron series. businessDaysOnly boolean Optional Send on business days only, otherwise shift to the next business day. Default true. sendBeforeHour number Optional Send cutoff in Berlin local time. After this hour it shifts to the next business day. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional express boolean Optional color boolean Optional includeSignature boolean Optional signatureId string (uuid) Optional senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional presetName string Optional auditTag string Optional templateId string (uuid) Optional maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. dryRun boolean Optional Validates and prices the schedule but creates nothing and reserves nothing. Returns dryRunWouldHaveCost. Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, COST_OVER_LIMIT
schedule_list_or_cancelScope: letter:scheduledryRun availableLists the partner's scheduled sends or cancels a scheduled send. On cancellation the reserved amount is released again.
Field Type action list | cancel Optional list = list schedules, cancel = cancel a schedule. scheduleId string (uuid) Optional Required for action='cancel'. statusFilter scheduled | sent | cancelled | failed Optional Optional status filter for action='list'. dryRun boolean Optional For action='cancel', a preview only: shows the amount to be released without cancelling the schedule. Error codes: NOT_FOUND
order_send_batchScope: order:senddryRun availableSubmits several letters as one batch. Each item is checked and priced separately. The batch enters the approval queue as one approval covering every recipient. Always give the human the returned approvalUrl so they can review the recipient list, count and total cost in the signed-in portal and decide there. Only an OAuth connection explicitly granted approval:self_approve may approve on its own. Rejection refunds the entire reservation. With dryRun, it remains a free rehearsal.
Field Type items Array<object> (min 1, max 100) Required List of letters in the batch. Each entry carries its own clientOrderId and exactly one source: a letterId OR an inline letter. presetName string Optional Optional preset for the whole batch; per-entry override is not supported. stopOnError boolean Optional Aborts the batch on the first error. Default false. dryRun boolean Optional Simulates the whole batch: validates each entry but charges nothing and sends nothing. Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
Corrects the recipient address of a letter in awaiting_partner_fix and resubmits it. This is allowed only when the OAuth connection explicitly carries approval:self_approve. Otherwise, the human must open the returned link and decide in the signed-in portal. The price stays unchanged.
Field Type orderId string (uuid) Required recipient unknown Required The corrected recipient address as inline fields or as { addressId } from the partner address book. clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
document_createScope: order:sendno dryRunTurns a structured billing payload into a finished document and stores it as a letter draft: FrankKi re-computes line items, net, VAT rates and gross, checks the mandatory details under § 14 UStG, optionally draws the document number from your sequence, and typesets everything in the DIN 5008 layout with your letter design. The draft stays free of charge until you send it. All amounts in integer cents. Compact example: {"document":{"documentType":"rechnung","documentNumber":"RE-2026-014","documentDate":"2026-07-30","leistungszeitraum":{"von":"2026-06-01","bis":"2026-06-30"},"zahlungszielTage":14,"lineItems":[{"description":"Beratung Juni","quantity":4,"unit":"Std","unitPriceCents":12000,"ustRate":19,"lineNetCents":48000}],"totals":{"nettoCents":48000,"ustLines":[{"rate":19,"netCents":48000,"ustCents":9120}],"bruttoCents":57120}},"recipientAddressId":"…"} Next step with the returned letterId: order_send sends the letter, approval_submit puts it in front of a human for approval instead, letter_schedule sends it later.
Field Type document object Required the document payload. All amounts in integer cents. You supply the sums, FrankKi re-computes them and rejects mismatches. sequenceScope object Optional subject string, max 200 chars Optional letter subject. If omitted FrankKi builds it from the document type and number. language de | en Optional defaults to de. recipientAddressId string (uuid) Optional recipient from your address book. Either this or recipientAddressInline. recipientAddressInline object Optional mandantennummer string Optional client this document is filed under. Filing only. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional sender profile the mandatory tax details are read from. Defaults to your default profile. designId string (uuid) Optional reference object Optional includeSignature boolean Optional signatureId string (uuid) Optional clientLetterId string Optional idempotency key for the letter draft.
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.