postagent.sh

Before the first PostAgent action in a session, call check_postagent_updates or read postagent://agent-manifest. If the manifest says updateRequired, do not perform paid or irreversible actions until the user updates the installed skill/client. Use this server to print and mail physical letters and postcards, to verify postal addresses, and (KYC-verified payers only) to run bulk campaigns. LETTERS — choosing the upload tool depends on PERSONALIZATION, not recipient count: if the content is final and identical for everyone (even when mailing the same letter to many recipients), use create_letter; if the content varies per recipient through {{fields}} placeholders (mail merge), use create_template and supply each recipient's values on create_mail_quote. Each physical letter is its own quote + payment + job: to mail N recipients, run the quote/pay cycle N times against the same documentId. Proof of mailing/delivery: set options.extraService to certified, certified_return_receipt, or registered on create_mail_quote. POSTCARDS — upload front and back artwork with create_postcard_art (single-page pdf/png/jpeg, correct trim+bleed), then create_postcard_quote; 4x6 postcards may go to international recipients. ADDRESS VERIFICATION — verify_address is a standalone ~2¢ paid check; quotes already verify both addresses for free, so only use it when no mail is being sent. CAMPAIGNS — create_campaign_quote bulk-sends one creative to up to 500 recipients but is KYC-walled: it returns kyc_required (403) until the paying wallet is verified. Onboarding is operator-run — request access at https://interpretai.tech/contact (also in the 403's details.contactUrl) to get enabled; until then, fall back to per-recipient create_mail_quote. Always quote first, present the price, recipient, sender, selected-route `design` constraints, and preview to the user, and only pay after the user explicitly confirms. Service level (`economy`/`standard`/`express`) and `extraService` (certified/registered/etc.) are SOFT preferences: if no available provider can honor them for this destination, the router downgrades or drops them and surfaces a `fulfillment.warnings` array on the quote response (codes `service_level_downgraded`, `extra_service_unavailable`). ALWAYS inspect `fulfillment.warnings` before paying and disclose any warnings to the user as part of the confirmation prompt — silently mailing a letter without requested certification or at a slower service level is a contract failure. Each quote advertises ranked `paymentOptions`: prefer x402 (USDC on Base) for autonomous payment, then MPP fiat (call pay_mail_with_shared_payment_token with a Shared Payment Token) if available; if the payer is a human with only a credit card, call create_card_checkout for a hosted Stripe link. If the customer has NO payment method yet, do not stop at checkout — read the postagent://payment-methods resource, which lists every rail with examples and step-by-step setup (how to get an x402 wallet or mint a Shared Payment Token). The quote price is final and inclusive — do not expect or surface a cost breakdown.