postalform-agent-mailing_skill

Overview

This skill automates sending real postal mail through PostalForm using machine payments. It prepares and validates print-and-mail payloads, submits POST /api/machine/orders with strict idempotency, settles x402 payments via a compatible wallet client, and polls order fulfillment until completion. Designed for strong first-pass correctness and safe retry behavior.

How this skill works

Collect required buyer/sender/recipient inputs and a PDF source, then build a stable payload using a single UUID request_id for idempotent retries. Optionally preflight with the /validate endpoint to confirm page count and quoted price. Submit the order to receive a 402 PAYMENT-REQUIRED, sign and settle the x402 payment with purl or another x402-compatible client, then resend the identical payload with PAYMENT-SIGNATURE and poll the order endpoint until is_paid and order_complete_url indicate completion.

When to use it

• An agent must autonomously mail a physical letter or document with high reliability.
• You need idempotent retry behavior for print-and-mail orders to avoid duplicates.
• When on-chain or network payment settlement is required (x402 flow).
• When you must validate page counts and price before committing funds.
• When you need programmatic polling to detect fulfillment and final URLs.

Best practices

• Generate one UUID request_id and keep the entire payload bytes identical across retries.
• Always include buyer_email on every request (required for receipts).
• Use one address strategy per party: Manual or Loqate; do not mix for the same party.
• Omit optional fields (like line2) unless they are non-empty strings to avoid validation errors.
• Match the payment network to the PAYMENT-REQUIRED response; do not hardcode networks.
• Prefer encrypted keystore wallets and use a max-amount limit when invoking purl or other clients.

Example use cases

• Send a legally signed PDF contract to a customer by mail after online acceptance.
• Automated invoicing via physical mail when an electronic payment path is unavailable.
• Retry-safe dispatch of regulatory compliance documents that must be printed and mailed.
• Agent workflow that collects form data, generates a PDF, and ensures physical delivery with settlement metadata.