Zum Inhalt springen
FrankKi
Sign inStart freeiOS Download

Destination and quoting guide

Worldwide physical-mail API for AI agents

Ask the service about one destination and postal product at a time. Do not turn a worldwide routing policy into an all-countries guarantee.

FrankKi source supports worldwide physical-letter delivery through Pingen, conditional on the destination being admitted by current country policy, its shipping zone being open, and Pingen accepting and successfully pricing the request. Current country and tier counts are not measured. International prices, products, carriers, and timing are destination-specific, so shipping_quote is authoritative and an unavailable result must remain unavailable.

Worldwide is a conditional decision path

The source separates a broad country policy from narrower named postal products. A valid ISO country code can still be denied by policy, closed by rollout, rejected by the provider, or fail pricing. Conversely, the absence of a named catalog row does not by itself prove that standard physical delivery is impossible because Pingen virtual products can select an appropriate physical product for an accepted destination.

This is why a static country table would be misleading. The current live rollout, provider response, and country-by-country tier inventory were not verified here. No fixed country count is claimed, and missing live coverage is not represented as zero.

Validate, preview, and quote the exact destination

Validate the full recipient address before drafting or sending. Render the final letter, then request a quote with the exact ISO country, page count or reviewed letterId, color mode, and requested delivery type. The send uses the same server-authoritative pricing path and returns unavailable instead of inventing a price.

address_validate({
  "name": "Example Recipient",
  "street": "Example Street",
  "houseNumber": "1",
  "zip": "EXAMPLE_POSTCODE",
  "city": "Example City",
  "country": "CH"
})

shipping_quote({
  "letterId": "REVIEWED_LETTER_ID",
  "pageCount": 1,
  "color": false,
  "deliveryType": "standard",
  "country": "CH"
})

Boundary: The address and IDs are placeholders. The example performs no send and provides no hardcoded quote result. Use only the options returned for the real destination.

Standard, tracked, and registered are different

The worldwide standard baseline is estimated and untracked, with no proof of delivery. A distinct price tier may establish a tracked option, but a price difference does not establish registered mail, recipient signature, or proof of delivery.

Registered mail is available only when a real named product in the destination catalog carries the registered marker. If that evidence is absent, the source returns LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY rather than silently downgrading the request. Germany has source-defined Einwurf and Uebergabe products; Switzerland has a named registered product; Austria has no registered tier in the checked source. Recheck the actual destination at quote time.

  • Tracking is a carrier number and status timeline.
  • Proof of posting records a provider-reported or observed posting event.
  • Proof of delivery or a recipient signature exists only where the selected product returns it.
  • None of these artifacts by itself establishes legal sufficiency or legal effect.

Treat unavailable as a real outcome

Stop when address validation returns COUNTRY_NOT_SUPPORTED, quote resolution is unavailable, the requested registered product returns LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, or the send reports PRICE_CHANGED. Do not substitute a country, delivery tier, or provider and do not remove a registered-mail requirement to force a quote.

If a price changes, request a fresh quote and present the new destination, product, artifact, price, and maxCostEuros to the human for a new decision. Preserve the stable clientOrderId only for a retry of the unchanged operation.

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.