Dedicated tool guide

order_send

Run the full send gates, optionally as a dry run, then queue a physical-mail order for human approval.

Generated contract: apiVersion v1, schemaRevision 2. Examples use placeholders and do not call production.

`order_send`

actionscope: order:send

Sends a letter by post: checks the sender's mandatory details, the recipient address, the AVV and the limits, creates the PDF and calculates the price. The letter arrives via letterId (a draft) or inline: then the body is 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}]}]} Schema reference: frankki://blocks-guide. dryRun: true is a free rehearsal: it returns the price, page 1 as an image and the checks list (each gate with passed, failed or skipped), and the letter stays unsent; a second call with the same values and dryRun: false sends exactly that letter. A real send waits for approval. Autopilot is a dashboard setting the person controls: with it, a standard letter from an own released template (templateId plus templateVersionId) to an address-book recipient leaves after 10 minutes. saveRecipient: true adds the recipient on the way, humanSummary names the time, order_status and order_cancel take the approvalId. mcp_health reports under setup which approval path applies. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. A finished own PDF goes out unchanged: letter_upload_pdf checks and stores it, then order_send sends it with pdfStorageKey and the recipient.

Input contract

Field	Type	Requirement	Meaning
`letterId`	string	optional	Existing draft. The letter can come inline instead.
`pdfStorageKey`	string	optional	The key from letter_upload_pdf, when an own finished PDF is the letter, in place of subject and body. It goes with the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move.
`subject`	string	optional
`content`	string	optional	Letter body as plain text. Exactly one of content and blocks.
`blocks`	array<object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object>	optional	Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes.
`styleDefs`	object	optional	Named document styles (max 24); blocks reference them via style.
`recipientAddressId`	string	optional	A saved address from the address book (address_list) as the recipient, in place of the fields recipientName to recipientCountry.
`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	optional
`letterheadId`	string	optional	A specific letterhead for this send. If omitted, the default letterhead is used.
`letterheadEnabled`	boolean	optional	false leaves the letterhead off for this one send.
`senderAddressId`	string	optional
`senderProfileId`	string	optional
`mandantennummer`	string	optional
`clientOrderId`	string	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	optional
`approvalMode`	auto \| draft \| review	optional	How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. 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. letter_create_draft creates a draft with no wallet cover.
`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	optional
`templateVersionId`	string	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	optional	Cover letter for a standalone form template.
`coverTemplateVersionId`	string	optional	Exact released version of the cover letter.
`designId`	string	optional	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, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode.
`dryRun`	boolean	optional	Free rehearsal; returns page 1 as an image and the checks list (each gate with passed, failed or skipped).
`saveRecipient`	boolean	optional	true saves the recipient to the address book with this send (for autopilot).
`includeGeometry`	boolean	optional	Also returns the page layout data.

Contract-shaped example

order_send({
  "letterId": "REVIEWED_LETTER_ID",
  "recipientName": "Max Mustermann",
  "recipientStreet": "Musterstrasse",
  "recipientHouseNumber": "1",
  "recipientZip": "10115",
  "recipientCity": "Berlin",
  "recipientCountry": "DE",
  "deliveryType": "einschreiben_einwurf",
  "priceVersion": "VERSION_FROM_QUOTE",
  "quotedUnitPriceCents": UNIT_PRICE_CENTS_FROM_QUOTE,
  "maxCostEuros": 10,
  "approvalMode": "review",
  "clientOrderId": "contract-482-send-v1",
  "dryRun": true
})

Replace quotedUnitPriceCents with the exact value returned by shipping_quote. Reuse the same clientOrderId and payload for retries; remove dryRun only for an intentional live submission.

For conditional fields and nested object limits, the generated complete tool reference remains authoritative. See errors and safe agent onboarding before implementing retries or a live send.

Trust and live status

Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.

Service facts (JSON) ↗Live status ↗