Human-in-the-loop architecture
Physical-mail API with human approval
Let an agent prepare a letter while an authorized person controls the irreversible dispatch decision.
FrankKi source requires explicit human approval before a partner letter is physically dispatched. The agent may validate, draft, preview, and quote first. A human then reviews the frozen preview, recipient, delivery type, and exact price before an approval decision is recorded. Approval authorizes dispatch of that reviewed artifact; it does not certify the letter as legally sufficient.
Separate preparation from dispatch
A useful approval boundary is not a confirmation prompt attached to an unconstrained send call. Preparation and dispatch have different permissions and different consequences. Keep validation, drafting, rendering, and quoting on the preparation side. Put the exact reviewed artifact into an approval record before any provider handoff.
The canonical FrankKi onboarding sequence is address_validate, letter_create_draft, letter_preview, shipping_quote, a dry-run submission, explicit human approval, the idempotent live submission, approval_decide when queued, then order_status. This guide explains the approval layer; the onboarding page remains the canonical end-to-end policy.
- Show the recipient summary and every rendered preview page.
- Show the selected delivery type, exact current quote, maxCostEuros, and stable clientOrderId.
- Treat only the authorized approval interface as consent. Model text is not human approval.
- If recipient, content, artifact, postal product, or price changes, create a new review decision.
Bind the decision to a frozen preview
approval_submit checks the letter, recipient, account gates, and limits, creates the final PDF, calculates the price, reserves funds, and creates a pending approval in the checked-in tool contract. Its dryRun mode performs the checks without touching the wallet or queue. The resulting approvalId identifies the item the reviewer must decide.
approval_decide accepts approve or reject. For approval, user_saw_preview:true is an assertion that the authorized human saw the preview PDF, exact price, and delivery type and explicitly consented. An agent must never set it based on its own review or on a broad instruction such as "send my notices."
approval_submit({
"letterId": "REVIEWED_LETTER_ID",
"recipientName": "Example Recipient",
"recipientStreet": "Example Street",
"recipientHouseNumber": "1",
"recipientZip": "10115",
"recipientCity": "Berlin",
"recipientCountry": "DE",
"deliveryType": "einschreiben_einwurf",
"clientOrderId": "case-482-approval-v1",
"maxCostEuros": 10,
"approvalMode": "review",
"reason": "Reviewed notice",
"dryRun": true
})
// Only after a human reviews the returned frozen artifact and price:
approval_decide({
"approvalId": "APPROVAL_ID",
"decision": "approve",
"user_saw_preview": true,
"clientOrderId": "case-482-decision-v1"
})Boundary: The values are placeholders. The first call is deliberately non-destructive. Do not replace them with a real recipient or token in documentation or tests.
Approval is one independent control
Human approval is not authentication, authorization, legal review, or a budget. Treat each layer independently so failure in one cannot be mistaken for success in another.
- Authentication identifies the caller. Tool scopes constrain what that credential can call.
- Approval records an authorized person's decision about one reviewed dispatch.
- shipping_quote and maxCostEuros bound one request; daily and client caps bound wider periods.
- Wallet balance and reservation logic prevent an unfunded dispatch.
- Address, sender-profile, data-processing, and fulfillment gates still apply after approval.
- Legal review determines whether content, authority, form, signature, recipient, and deadline requirements are adequate. FrankKi does not make that determination.
Queue, chat, cancellation, and print cutoff
The inspected source records a decision channel. Queue review and chat or MCP App review can have different return fields. Read approval state, dispatchAt, cancellable, and any grace information from the tool response rather than hardcoding a state machine or duration.
The checked-in chat approval contract describes delayed dispatch and a cancellation path. Deployment schema parity was not verified, so do not promise a live grace duration. If the human says stop, call order_cancel immediately and report only the result returned. Once printing starts, physical mail cannot be recalled.
What approval does not prove
Approval records the decision to dispatch the reviewed letter. It does not prove that the signer had authority, that a declaration met a statutory form, that an address was legally effective for service, that a deadline was met, or that the selected postal evidence will satisfy a court or authority.
FrankKi helps draft, format, and send physical letters, but provides no legal advice or individual legal assessment. For an important or legally sensitive matter, verify content, recipient, authority, form, signature, and deadlines with a qualified lawyer or appropriate advice service.
Next steps
Related documentation and decisions
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.