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 1 · 47 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
mcp_healthHealth-/Echo-Probe - prüft das Partner-Token und die Verarbeitungskette von Anfang bis Ende. EN: Health/echo probe - verifies the partner token and the chain end to end.
No input fields besides reasoning.
profile_getScope: profile:readComing soonLiefert das Partnerprofil im Überblick: Standard-Absenderadresse, hinterlegte Signatur und Briefkopf, gespeicherte Presets und eine kurze Wallet-Zusammenfassung. EN: Returns an overview of the partner profile: default sender address, stored signature and letterhead, saved presets and a short wallet summary.
No input fields besides reasoning.
wallet_balanceScope: wallet:readComing soonLiefert den aktuellen Wallet-Stand: Guthaben, Tageslimit für Briefe und Kosten sowie den nächsten Reset-Zeitpunkt. EN: Returns the current wallet status: balance, daily cap for letters and costs, and the next reset time.
No input fields besides reasoning.
sender_profile_listScope: sender_profile:readComing soonListet alle Absenderprofile des Partners mit ihrer Rechtsform und ob die Pflichtangaben vollständig sind. EN: Lists 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:readComing soonLiefert ein einzelnes Absenderprofil mit allen Pflichtangaben, Bankverbindung und Disclaimer. EN: Returns 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:readComing soonLiefert einen Mandanten mit Adressen, Kategorie, Sachbearbeiter, Monatslimit, verbrauchtem Monatsbudget, Aufbewahrungsdauer und der Briefanzahl der letzten 12 Monate. EN: Returns 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:readComing soonListet die Mandanten des Partners, optional gefiltert nach Suchbegriff, Kategorie oder Tag. EN: Lists 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 Nur Mandanten, die seit diesem Zeitpunkt angelegt wurden (ISO 8601). EN: Only clients created since this time (ISO 8601). limit integer Optional Standard 20, maximal 100. EN: Default 20, maximum 100. offset integer Optional Versatz für die Seitennavigation. Standard 0. EN: Offset for pagination. Default 0. mandant_searchScope: mandant:readComing soonSucht Mandanten über Mandantennummer, Name, Tags oder Sachbearbeiter und nennt für jeden Treffer die passende Spalte. EN: Searches clients (Mandanten) by client number, name, tags or case handler and names the matching column for each hit.
Field Type query string Required since string (date-time) Optional Nur Mandanten, die seit diesem Zeitpunkt angelegt wurden (ISO 8601). EN: Only clients created since this time (ISO 8601). limit integer Optional Standard 20, maximal 100. EN: Default 20, maximum 100. offset integer Optional Versatz für die Seitennavigation. Standard 0. EN: Offset for pagination. Default 0. template_listScope: template:readComing soonListet die verfügbaren Brief-Vorlagen mit Kategorie, Version und ihren Platzhaltern (Merge-Feldern). EN: Lists the available letter templates with category, version and their placeholders (merge fields).
Field Type kategorieFilter string Optional limit integer Optional Standard 20, maximal 100. EN: Default 20, maximum 100. offset integer Optional Versatz für die Seitennavigation. Standard 0. EN: Offset for pagination. Default 0. template_getScope: template:readComing soonLiefert eine einzelne Vorlage mit Betreff- und Inhaltsvorlage, den Merge-Feldern und der empfohlenen Freigabe- und KI-Kennzeichnungs-Voreinstellung. EN: Returns a single template with subject and content template, the merge fields and the recommended approval and AI-labelling default.
Field Type templateId string (uuid) Required Error codes: NOT_FOUND
letter_getScope: letter:readLiefert einen Brief des Partners samt zugehörigem Auftrag und einer 24 Stunden gültigen Download-URL für die PDF. EN: Returns 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:readComing soonListet die Briefe des Partners mit optionalen Filtern nach Empfängername, Betreff, Status und Zeitpunkt. EN: Lists 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:readComing soonPrüft, ob ein Absenderprofil (per profileId) oder ein vorgeschlagener Feldsatz alle Pflichtangaben für seine Rechtsform enthält. Liefert valid, missingFields und weiche Hinweise. Wirft nicht bei einer Lücke. EN: Checks whether a sender profile (by profileId) or a proposed field set contains all mandatory details for its legal form. Returns valid, missingFields and soft hints. Does not throw on a gap.
No input fields besides reasoning.
address_listScope: address:readComing soonListet die Adressen im Partner-Adressbuch. Optional nach Name, Stadt oder Mandant gefiltert. EN: Lists 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:readComing soonPrüft eine Adresse providerabhängig (DE über LetterXPress, AT/CH/Ausland über Pingen), ohne sie zu speichern. Bei harten Fehlern wird ADDRESS_INVALID zurückgegeben. EN: Validates an address by provider (DE via LetterXPress, AT/CH/international via Pingen) without storing it. Hard failures return ADDRESS_INVALID.
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-alpha-2, default DE. EN: 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:readComing soonFüllt die Platzhalter einer gespeicherten Vorlage mit deinen Werten und gibt Betreff und Inhalt zurück. Fehlt eine Pflichtangabe, bleiben Betreff und Inhalt leer und die offenen Felder werden gemeldet. EN: Fills the placeholders of a saved template with your values and returns subject and content. If a required value is missing, subject and content stay empty and the open fields are reported.
Field Type templateId string (uuid) Required Id der Vorlage aus template_list / template_get. EN: The template ID from template_list / template_get. mergeValues object Optional Zuordnung von Platzhalter-Namen zu Werten, z. B. { "provider": "Telekom" }. EN: Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. mandantennummer string Optional Optionaler Mandantenbezug (nur Kontext). EN: Optional client reference (context only). Error codes: NOT_FOUND
shipping_quoteScope: letter:readComing soonErmittelt den Preis, das Briefformat, die Versandart und die voraussichtliche Laufzeit für einen Brief, ohne ihn zu versenden. EN: Determines the price, letter format, shipping method and estimated delivery time for a letter without sending it.
Field Type pageCount integer Required color boolean Required deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe Required express boolean Optional country string Optional ISO 3166-1 alpha-2, Standard DE. EN: ISO 3166-1 alpha-2, defaults to DE. letterId string (uuid) Optional Optional: die letterId eines bestehenden Entwurfs, damit der Preis exakt zu dem passt, was order_send fuer denselben Brief berechnet. EN: Optional: the letterId of an existing draft so the price matches exactly what order_send charges for the same letter. order_statusScope: order:readLiefert den aktuellen Status eines Auftrags samt chronologischer deutscher Sendungsverfolgung, der Sendungsnummer (nur bei Einschreiben), der voraussichtlichen Zustellung und ob sich der Brief noch stornieren lässt. EN: Returns 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.
Field Type orderId string (uuid) Required Error codes: NOT_FOUND
order_einlieferungsbelegScope: order:readLiefert den Einlieferungsbeleg (Einlieferungsnachweis) zu einem versendeten Auftrag: eine 90 Tage gültige Download-URL für die Beleg-PDF, den Poststempel, den Versanddienstleister sowie den geprüften Nachweis aus dem GoBD-Archiv. EN: Returns 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:readComing soonListet die Freigaben deines Kontos, neueste zuerst, mit einer zeitlich begrenzten PDF-Vorschau, den Kosten, dem Grund und den Fristen. Standardmaessig nur die offenen Freigaben. EN: Lists 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.
Field Type status pending | approved | rejected | expired Optional Standard pending. EN: Default pending. since string (date-time) Optional Nur Freigaben, die seit diesem Zeitpunkt eingereicht wurden (ISO 8601). EN: Only approvals submitted since this time (ISO 8601). limit integer Optional Standard 20, maximal 100. EN: Default 20, maximum 100. offset integer Optional Versatz für die Seitennavigation. Standard 0. EN: Offset for pagination. Default 0. wallet_topup_linkScope: wallet:readComing soonErstellt einen Stripe-Checkout-Link zum Aufladen deines Wallet-Guthabens. Der MCP sieht keine Kartendaten; das Guthaben wird nach Abschluss der Zahlung gutgeschrieben. EN: Creates a Stripe checkout link to top up your wallet balance. The MCP never sees card data; the balance is credited once the payment completes.
Field Type amountEuros number Required Aufladebetrag in Euro, zwischen 10 und 500. EN: Top-up amount in euros, between 10 and 500. requestNonce string, max 200 chars Optional Optionaler stabiler Wiederholungs-Schluessel. Bei einer Wiederholung denselben Wert senden, um denselben Checkout-Link zu erhalten statt eines zweiten. EN: 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:readComing soonVergleicht deinen finalen Brief mit der Vorlage und zeigt dir, wo du abgewichen bist. Kostenlos und ohne Änderung. EN: Compares your final letter with the template and shows you where you deviated. Free and without any change.
Field Type templateId string (uuid) Required Id der Vorlage aus template_list / template_get. EN: The template ID from template_list / template_get. versionId string (uuid) Optional Optional: bestimmte Version, sonst die freigegebene. EN: Optional: a specific version, otherwise the released one. finalSubject string Required Dein finaler Betreff. EN: Your final subject line. finalContent string Required Dein finaler Brieftext. EN: Your final letter text. mergeFields object Optional Zuordnung der Platzhalter-Namen zu Werten, z. B. { "provider": "Telekom" }. EN: Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. Error codes: NOT_FOUND, TEMPLATE_READONLY_VIA_MCP
letter_design_listScope: letter_design:writeListet die gespeicherten Briefdesigns des Partners samt vollstaendigem Design-JSON. Ein Design wird per Name oder ID beim Versand referenziert. EN: Lists the partner's saved letter designs with the full design JSON. A design is referenced by name or id when sending.
Field Type includeArchived boolean Optional Auch archivierte (geloeschte) Designs einschliessen. Standard false. EN: Include archived (deleted) designs too. Defaults to false. letter_design_previewScope: letter_design:writeErstellt eine Vorschau-PDF eines Briefdesigns anhand einer Beispielseite und liefert einen kurzlebigen Vorschau-Link. Verletzt das Design eine geschuetzte Zone, wird die Vorschau trotzdem erstellt: die betroffenen Stellen sind rot markiert und violations listet die Details. Es wird nichts berechnet und nichts versendet. EN: Renders a preview PDF of a letter design using a sample page and returns a short-lived preview link. If the design violates a protected zone the preview still renders: the affected areas are marked in red and violations lists the details. Nothing is charged and nothing is sent.
Field Type designId string (uuid) Optional Ein gespeichertes Briefdesign in der Vorschau anzeigen. Alternativ ein noch nicht gespeichertes design inline angeben. EN: Preview a saved letter design. Alternatively provide a not-yet-saved design inline. design object Optional Ein noch nicht gespeichertes Briefdesign in der Vorschau pruefen (gleiche Struktur wie in letter_design_save). EN: Preview a not-yet-saved letter design (same structure as in letter_design_save). reference object Optional Beispielwerte fuer diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie fuellen Infoblock und Barcode in der Vorschau. EN: Sample per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and barcode in the preview. sampleSubject string, max 200 chars Optional Betreff fuer die Beispielseite. EN: Subject for the sample page. sampleContent string, max 4000 chars Optional Brieftext fuer die Beispielseite. EN: Letter body for the sample page. Error codes: DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
signature_listScope: profile:readComing soonListet die im Partnerprofil gespeicherten Unterschriften mit einer kurzlebigen Vorschau-URL (24 Stunden gültig). EN: Lists 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:readComing soonListet die im Partnerprofil gespeicherten Briefköpfe mit einer kurzlebigen Vorschau-URL (24 Stunden gültig). EN: Lists 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:readSucht Firmen und Behörden im Verzeichnis und liefert die passende Versandadresse inklusive Behörden-Postfach. EN: Searches 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:readDurchsucht die Briefe des Partners per Freitext über Betreff, Empfängername und Briefinhalt. EN: Full-text searches the partner's letters across subject, recipient name and letter content.
Field Type query string Required since string (date-time) Optional Nur Briefe, die seit diesem Zeitpunkt geändert wurden (ISO 8601). EN: Only letters modified since this time (ISO 8601). limit integer Optional Standard 20, maximal 100. EN: Default 20, maximum 100. offset integer Optional Versatz für die Seitennavigation. Standard 0. EN: Offset for pagination. Default 0. archive_exportScope: archive:readComing soonPlant einen Archiv-Export (GoBD-CSV, DATEV, PDF-Bundle oder Mandanten-Allokation) für einen Zeitraum ein und liefert eine Job-ID zur Statusabfrage. EN: Schedules 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:readComing soonLiefert den Status eines Archiv-Export-Jobs und bei Fertigstellung eine 90 Tage gültige Download-URL. EN: Returns 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
Action
address_upsertScope: address:writeno dryRunComing soonLegt eine Adresse im Partner-Adressbuch an oder aktualisiert sie. Validiert die Adresse providerabhängig (DE über LetterXPress, AT/CH/Ausland über Pingen). EN: Creates or updates an address in the partner address book. Validates the address by provider (DE via LetterXPress, AT/CH/international via Pingen).
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-alpha-2, default DE. EN: ISO 3166-1 alpha-2, defaults to DE. mandantennummer string Optional addressType recipient | sender | billing Optional isDefault boolean Optional Error codes: ADDRESS_INVALID
letter_create_draftScope: order:sendno dryRunComing soonLegt einen Briefentwurf an: erstellt eine Vorschau-PDF (nur Brieftext, ohne Anhaenge), speichert den Entwurf und liefert eine Seitenzahl, einen Vorschau-Link (24 Stunden gueltig) und eine unverbindliche Kostenvorschau. Es wird nichts berechnet und nichts versendet. EN: Creates a letter draft: produces a preview PDF (letter body only, no attachments), stores the draft and returns a page count, a preview link (valid for 24 hours) and a non-binding cost estimate. Nothing is charged and nothing is sent.
Field Type subject string, max 200 chars Required content string, max 30000 chars Required language de | en Optional Standard de. EN: Defaults to de. senderAddressId string (uuid) Optional recipientAddressInline object Optional presetName string Optional kiKennzeichnung boolean Optional clientLetterId string Optional Idempotenzschluessel. Ein erneuter Aufruf mit demselben Wert liefert denselben Entwurf, statt einen zweiten anzulegen. EN: Idempotency key. A repeat call with the same value returns the same draft instead of creating a second one. designId string (uuid) Optional Ein gespeichertes Briefdesign fuer diesen Brief verwenden. Es wird am Entwurf gespeichert, sodass ein spaeterer Versand ueber die letterId es uebernimmt (ausser der Versand nennt selbst ein Design). Ohne Angabe gilt beim Versand das Standard-Design des Absenderprofils oder keins. EN: Use a saved letter design for this letter. It is 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 at send time, or none. reference object Optional 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. attachment_upload_pdfScope: order:sendno dryRunComing soonLädt ein PDF als Anhang zu einem Partner-Brief hoch. Prüft vor dem Speichern die Dateigröße (max. 50 MB) und die zusammengeführte Seitenzahl (max. 30 Seiten inkl. Brief und übriger Anhänge). EN: Uploads 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 Öffentliche URL des PDF (Alternative zu pdfBase64). EN: Public URL of the PDF (alternative to pdfBase64). pdfBase64 string Optional PDF als Base64 (Alternative zu pdfUrl). EN: PDF as Base64 (alternative to pdfUrl). title string Optional position integer Optional attachment_upload_imageScope: order:sendno dryRunComing soonLädt ein Bild (PNG/JPEG) als Anhang zu einem Partner-Brief hoch. Das Bild wird serverseitig auf eine A4-PDF-Seite skaliert (optional gedreht) und wie ein PDF gespeichert. Prüft vor dem Speichern die zusammengeführte Seitenzahl (max. 30 Seiten). EN: Uploads 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).
Field Type letterId string (uuid) Required imageUrl string Optional Öffentliche URL des Bildes (Alternative zu imageBase64). EN: Public URL of the image (alternative to imageBase64). imageBase64 string Optional Bild als Base64 (Alternative zu imageUrl). EN: Image as Base64 (alternative to imageUrl). rotation 0 | 90 | 180 | 270 Optional Drehung in Grad. EN: Rotation in degrees. title string Optional position integer Optional order_sendScope: order:senddryRun availableVersendet einen Brief physisch per Post: prueft die Pflichtangaben des Absenders, die Empfaengeradresse, den AVV und die Limits, erstellt die finale PDF, berechnet den Preis und gibt den Versand frei. Mit dryRun wird der Versand nur simuliert, ohne etwas zu berechnen oder zu versenden. 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, calculates the price and releases the send. With dryRun the send is only simulated, without charging or sending anything.
Field Type letterId string (uuid) Optional Bestehender Entwurf. Alternativ den Brief inline angeben. EN: 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-alpha-2, Standard DE. EN: ISO 3166-1 alpha-2, defaults to DE. priceVersion string Optional 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. quotedUnitPriceCents integer Optional 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. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe Optional Standard standard. EN: Defaults to standard. express boolean Optional color boolean Optional Ohne Angabe wird die Farbe automatisch erkannt. EN: If omitted, colour is detected automatically. includeSignature boolean Optional signatureId string (uuid) Optional letterheadId string (uuid) Optional 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. letterheadEnabled boolean Optional Auf false setzen, um den Briefkopf fuer diesen einen Versand zu unterdruecken. EN: Set to false to suppress the letterhead for this one send. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional clientOrderId string Optional Idempotenzschluessel. Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert. EN: Idempotency key. 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 maxCostEuros number Optional Maximalbetrag in Euro. Liegt der Preis darueber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional kiKennzeichnung boolean Optional templateId string (uuid) Optional designId string (uuid) Optional 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. reference object Optional 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. 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
approval_submitScope: order:senddryRun availableComing soonReicht einen Brief zur menschlichen Freigabe ein, statt ihn sofort zu versenden: prueft Pflichtangaben, Empfaenger, AVV und Limits, erstellt die finale PDF, berechnet den Preis, reserviert die Kosten und legt eine Freigabe in der Warteschlange an. Mit dryRun wird nur geprueft, ohne etwas zu reservieren oder einzureichen. EN: Submits a letter for human approval instead of sending it right away: checks mandatory details, recipient, AVV and limits, creates the final PDF, calculates the price, reserves the cost and adds an approval to the queue. With dryRun it only validates, without reserving or submitting anything.
Field Type letterId string (uuid) Optional Bestehender Entwurf. Alternativ den Brief inline angeben. EN: 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-alpha-2, Standard DE. EN: ISO 3166-1 alpha-2, defaults to DE. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe Optional Standard standard. EN: Defaults to standard. express boolean Optional color boolean Optional Ohne Angabe wird die Farbe automatisch erkannt. EN: 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 Idempotenzschluessel. Ein erneuter Aufruf mit demselben Wert liefert dieselbe Freigabe, statt ein zweites Mal einzureichen. Der Praefix 'approval:' ist reserviert. EN: 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 Maximalbetrag in Euro. Liegt der Preis darueber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional kiKennzeichnung boolean Optional templateId string (uuid) Optional reason string, max 500 chars Optional Kurzer Grund fuer die Freigabe, den die pruefende Person auf der Karte liest. EN: Short reason for the approval, shown to the reviewer on the card. requesterContext string, max 500 chars Optional Zusatzkontext zur einreichenden Person oder zum Anlass. EN: 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
approval_decideScope: approval:decideno dryRunComing soonGibt eine wartende Freigabe im Namen des Menschen frei oder lehnt sie ab. WICHTIG: Bevor du hier 'approve' aufrufst, MUSST du dem Menschen (a) den Vorschau-Link (previewUrl) des Briefs, (b) den genauen Gesamtpreis in Euro und (c) die Versandart (z. B. Einschreiben Uebergabe oder Standard) zeigen und seine ausdrueckliche Zustimmung einholen; setze dann user_saw_preview:true. Bei Freigabe per Chat wird der Brief NICHT sofort versendet, sondern erst nach 10 Minuten; bis dahin kann der Mensch stoppen (sage einfach 'stopp', dann rufst du order_cancel auf). Bei Ablehnung bleibt der Brief ein Entwurf und die Reservierung wird zurueckgebucht. EN: Approves or rejects a pending approval on the human's behalf. IMPORTANT: before calling 'approve' here you MUST show the human (a) the preview link (previewUrl) of the letter, (b) the exact total price in euros and (c) the delivery type (e.g. registered mail hand delivery or standard) and obtain their explicit consent; then set user_saw_preview:true. A chat approval does NOT dispatch immediately: the letter is sent after 10 minutes and can be stopped until then (if the human says 'stop', call order_cancel). On rejection the letter stays a draft and the reservation is refunded.
Field Type approvalId string (uuid) Required decision approve | reject Required comment string, max 1000 chars Optional user_saw_preview boolean Optional Bestaetigung, dass du dem Menschen die Vorschau-PDF, den genauen Preis und die Versandart gezeigt und seine Zustimmung eingeholt hast. Fuer eine Freigabe erforderlich. EN: Confirmation that you showed the human the preview PDF, the exact price and the delivery type and obtained consent. Required to approve. clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
Error codes: APPROVAL_ALREADY_DECIDED, NOT_FOUND
order_cancelScope: order:sendno dryRunComing soonStorniert einen Brief und schreibt den Betrag deinem Wallet gut (geschlossener Kreislauf, keine Kartenerstattung). Mit orderId wird eine bereits erstellte Bestellung im Stornofenster storniert; ist der Brief bereits im Druck, wird sauber abgelehnt. Mit approvalId wird eine per Chat freigegebene Sendung im 10-Minuten-Stornofenster gestoppt, bevor sie ueberhaupt versendet wird (der Mensch sagt 'stopp'). EN: Cancels a letter and credits the amount to your wallet (closed loop, no card refund). 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 Die zu stornierende Bestellung. EN: The order to cancel. approvalId string (uuid) Optional Statt orderId: eine per Chat freigegebene Sendung im 10-Minuten-Stornofenster stoppen, bevor sie versendet wird (der Mensch sagt 'stopp'). EN: 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 Optionaler Stornogrund. EN: Optional cancellation reason. Error codes: NOT_FOUND
preset_saveScope: preset:writeno dryRunSpeichert eine benannte Voreinstellung (Konfigurations-Bundle) im Partnerprofil. Der Name ist pro Partner eindeutig. Limits in der Voreinstellung werden unverändert gespeichert, aber von keinem Versand- oder Lesepfad ausgewertet und können die Durchsetzung daher nicht beeinflussen. Maßgeblich bleiben die im Web gesetzten Konto- und Sub-Wallet-Limits. EN: Saves a named preset (configuration bundle) in the partner profile. The name is unique per partner. Limits inside the preset are stored as-is but are not evaluated by any send or read path and therefore cannot affect enforcement. The account and sub-wallet limits set in the web app remain authoritative.
Field Type name string Required Eindeutiger Name der Voreinstellung (pro Partner). EN: Unique name of the preset (per partner). preset object Required Das Konfigurations-Bundle (Absender/Unterschrift/Briefkopf, Versand, Kennzeichnung, Freigabe, Planung, Limits, auditTagPrefix). EN: The configuration bundle (sender/signature/letterhead, shipping, labelling, approval, scheduling, limits, auditTagPrefix). signature_uploadScope: signature:writeno dryRunComing soonLädt eine Unterschrift als PNG hoch und speichert sie im Partnerprofil. Die Unterschrift wird beim Versand zwischen Grußformel und gedrucktem Namen eingefügt. Nur PNG wird unterstützt. EN: Uploads a signature as PNG and stores it in the partner profile. On sending, the signature is inserted between the closing salutation and the printed name. Only PNG is supported.
Field Type pngBase64 string Required Die Unterschrift als PNG (Base64). EN: The signature as PNG (Base64). widthMm number Optional Gewünschte Breite in mm (optional). EN: Desired width in mm (optional). displayName string Optional Anzeigename der Unterschrift (optional). EN: Display name of the signature (optional). letterhead_uploadScope: letterhead:writeno dryRunComing soonLädt einen Briefkopf als PNG oder PDF hoch und speichert ihn im Partnerprofil. PNG wird auf die Seite gedruckt; ein PDF-Briefkopf wird vorerst nur gespeichert und nicht gedruckt (rendered=false). EN: Uploads a letterhead as PNG or PDF and stores it in the partner profile. PNG is printed on the page; a PDF letterhead is only stored for now and not printed (rendered=false).
Field Type fileBase64 string Required Der Briefkopf als PNG oder PDF (Base64). EN: The letterhead as PNG or PDF (Base64). widthMm number Optional Breite in mm (optional). EN: Width in mm (optional). heightMm number Optional Höhe in mm (optional). EN: Height in mm (optional). placement header | footer | full Optional Platzierung auf der Seite. EN: Placement on the page. displayName string Optional Anzeigename des Briefkopfs (optional). EN: Display name of the letterhead (optional). letter_design_saveScope: letter_design:writeno dryRunSpeichert ein wiederverwendbares Briefdesign (Briefpapier) im Partnerprofil und prueft sofort, dass alle Elemente die Zustellzonen einhalten. Ein ungueltiges Design wird mit einer genauen Meldung abgelehnt. EN: Saves a reusable letter design (letterhead) in the partner profile and immediately checks that all elements respect the delivery clear zones. An invalid design is rejected with a precise message.
Field Type name string Required Eindeutiger Name des Briefdesigns (pro Partner). EN: Unique name of the letter design (per partner). design object Required Das komplette Briefdesign. EN: The complete letter design. designId string (uuid) Optional Bestehendes Design aktualisieren. Ohne Angabe wird per Name angelegt oder ueberschrieben. EN: Update an existing design. If omitted, it is created or overwritten by name. Error codes: DESIGN_ZONE_VIOLATION
letter_design_deleteScope: letter_design:writeno dryRunArchiviert (loescht) ein gespeichertes Briefdesign. Es kann danach nicht mehr fuer neue Sendungen verwendet werden, bleibt aber fuer die Nachvollziehbarkeit bereits versendeter Briefe erhalten. EN: Archives (deletes) a saved letter design. It can no longer be used for new sends, but remains available for the auditability of already-sent letters.
Field Type designId string (uuid) Required Das zu loeschende Briefdesign. EN: The letter design to delete. Error codes: NOT_FOUND
letter_scheduleScope: letter:scheduledryRun availableComing soonPlant den Versand eines bestehenden Entwurfs für einen späteren Zeitpunkt (fester Termin, relative Verzögerung oder wiederkehrend per cron). Alle Prüfungen und der Preis werden sofort ermittelt und die Kosten reserviert; der eigentliche Versand läuft zum geplanten Zeitpunkt durch dieselbe Versandpipeline. EN: Schedules the sending of 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; the actual send runs at the scheduled time through the same send pipeline.
Field Type letterId string (uuid) Required Bestehender Entwurf, der geplant versendet wird. EN: Existing draft to be sent on schedule. mode at | in | cron Required at = fester Zeitpunkt, in = relative Verzögerung, cron = wiederkehrend. EN: at = fixed time, in = relative delay, cron = recurring. sendAt string (date-time) Optional Zeitpunkt bei mode='at' (ISO 8601, Berlin-Zeit wenn ohne Offset). EN: Time for mode='at' (ISO 8601, Berlin time if no offset). delay string Optional Verzögerung bei mode='in': '2d', '1w', '3h', 'next-business-day', 'next-monday', 'end-of-month'. EN: Delay for mode='in': '2d', '1w', '3h', 'next-business-day', 'next-monday', 'end-of-month'. cronExpression string Optional 5-Felder cron bei mode='cron': 'min std tag monat wochentag'. EN: 5-field cron for mode='cron': 'min hour day month weekday'. endDate string (date-time) Optional Enddatum für eine cron-Serie. EN: End date for a cron series. businessDaysOnly boolean Optional Nur an Werktagen versenden, sonst auf den nächsten Werktag verschieben. Standard true. EN: Send on business days only, otherwise shift to the next business day. Default true. sendBeforeHour number Optional Versand-Cutoff in Berliner Ortszeit. Nach dieser Stunde wird auf den nächsten Werktag verschoben. EN: Send cutoff in Berlin local time. After this hour it shifts to the next business day. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe 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 kiKennzeichnung boolean Optional templateId string (uuid) Optional maxCostEuros number Optional 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. dryRun boolean Optional Prüft und bepreist die Planung, legt aber nichts an und reserviert nichts. Liefert dryRunWouldHaveCost. EN: 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 availableComing soonListet die geplanten Sendungen des Partners auf oder bricht eine geplante Sendung ab. Beim Abbrechen wird die reservierte Summe wieder freigegeben. EN: Lists 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 = Planungen auflisten, cancel = eine Planung abbrechen. EN: list = list schedules, cancel = cancel a schedule. scheduleId string (uuid) Optional Erforderlich bei action='cancel'. EN: Required for action='cancel'. statusFilter scheduled | sent | cancelled | failed Optional Optionaler Statusfilter für action='list'. EN: Optional status filter for action='list'. dryRun boolean Optional Bei action='cancel' nur eine Vorschau: zeigt die freizugebende Summe, ohne die Planung abzubrechen. EN: 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 availableVersendet mehrere Briefe in einem Stapel. Jeder Eintrag wird einzeln geprueft, bepreist und versendet; ein fehlerhafter Eintrag bricht den Stapel nicht ab (ausser stopOnError ist gesetzt). Mit dryRun wird nichts berechnet und nichts versendet. EN: Sends several letters in one batch. Each entry is checked, priced and sent individually; a failing entry does not abort the batch (unless stopOnError is set). With dryRun nothing is charged and nothing is sent.
Field Type items Array<object> (min 1, max 100) Required Liste der Briefe im Stapel. Jeder Eintrag traegt seinen eigenen clientOrderId und genau eine Quelle: eine letterId ODER einen inline Brief. EN: 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 Optionales Preset fuer den ganzen Stapel; pro Eintrag ueberschreibbar ist nicht vorgesehen. EN: Optional preset for the whole batch; per-entry override is not supported. stopOnError boolean Optional Bricht den Stapel beim ersten Fehler ab. Standard false. EN: Aborts the batch on the first error. Default false. dryRun boolean Optional Simuliert den ganzen Stapel: prueft jeden Eintrag, berechnet aber nichts und versendet nichts. EN: 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
order_fix_resubmitScope: order:sendno dryRunComing soonKorrigiert die Empfaengeradresse eines Briefs, der auf eine Korrektur wartet (Status awaiting_partner_fix), und gibt ihn erneut zum Versand frei. Es wird nichts erneut berechnet: das reservierte Guthaben bzw. die bereits gebuchte Belastung bleibt bestehen. Bei einem Brief, der nicht auf eine Korrektur wartet, wird ORDER_NOT_FIXABLE zurueckgegeben. EN: Corrects the recipient address of a letter awaiting a fix (status awaiting_partner_fix) and releases it for sending again. Nothing is charged again: the reserved balance or the already-booked charge stays. Returns ORDER_NOT_FIXABLE for a letter that is not awaiting a fix.
Field Type orderId string (uuid) Required recipient unknown Required Die korrigierte Empfaengeradresse als Einzelfelder oder als { addressId } aus dem Partner-Adressbuch. EN: The corrected recipient address as inline fields or as { addressId } from the partner address book. clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
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.