{
  "schemaVersion": "1.0",
  "item": {
    "slug": "postalform-agent-mailing",
    "name": "Send real Document in the Mail via PostalForm",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/ggaabe/postalform-agent-mailing",
    "canonicalUrl": "https://clawhub.ai/ggaabe/postalform-agent-mailing",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/postalform-agent-mailing",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=postalform-agent-mailing",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "agents/openai.yaml",
      "references/payload_templates.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/postalform-agent-mailing"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/postalform-agent-mailing",
    "agentPageUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent",
    "manifestUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "PostalForm Machine Order",
        "body": "Use this workflow when an agent needs to send real postal mail (a physical print-and-mail order) reliably on the first attempt."
      },
      {
        "title": "1. Collect inputs and choose address strategy",
        "body": "Require these inputs:\n\nbuyer_name, buyer_email\nsender_name, recipient_name\nPDF source (upload_token, { download_url, file_id }, data URL, or allowed https URL)\nMailing options (double_sided, color, mail_class, certified)\n\nFor each party (sender, recipient), choose exactly one strategy:\n\nManual address: *_address_type: \"Manual\" + *_address_manual\nLoqate address: *_address_type: \"Address\" + *_address_id + *_address_text\n\nDo not mix manual + Loqate for the same party."
      },
      {
        "title": "2. Build payload with strict idempotency",
        "body": "Generate a UUID request_id once and keep payload bytes stable across retries.\n\nSet buyer_email every time (required for Stripe receipt routing).\n\nFor manual addresses:\n\nInclude line1, city, state, zip\nInclude line2 only when it has a non-empty string value\nOmit optional fields instead of sending null\n\nUse the tested template in references/payload_templates.md."
      },
      {
        "title": "3. Preflight with validate endpoint (recommended)",
        "body": "Call:\n\nPOST https://postalform.com/api/machine/orders/validate\n\nIf response is 200, confirm:\n\nquote.page_count matches expected page count\nquote.price_usd and options are acceptable\n\nIf response is 422, fix payload before paying."
      },
      {
        "title": "4. Create order and settle x402 payment",
        "body": "Endpoint:\n\nPOST https://postalform.com/api/machine/orders\n\nFlow:\n\nSend order payload without payment header.\nReceive 402 with PAYMENT-REQUIRED.\nCreate payment using your wallet stack on the requested network.\nRetry the exact same request body with PAYMENT-SIGNATURE.\nExpect 202 and settlement metadata.\n\nPayment client options:\n\npurl CLI (fastest path when available)\nAny x402-compliant client (@x402/core, @x402/evm, or equivalent custom signer flow)\n\nIf using purl:\n\nPrefer wallet alias/keystore over raw private keys\nUse --password from secure runtime input\nSet a protective --max-amount\nMatch --network to PAYMENT-REQUIRED network"
      },
      {
        "title": "5. Poll order status until post-payment completion",
        "body": "Call:\n\nGET https://postalform.com/api/machine/orders/:request_id\n\nTreat this as complete when:\n\nis_paid = true\ncurrent_step has advanced through processing (commonly to email_sent)\norder_complete_url is a real URL\n\nHandle transitional state:\n\nstatus: \"settled_pending_webhook\" can persist briefly after on-chain settlement\nContinue polling with backoff; do not resubmit a changed payload under the same request_id"
      },
      {
        "title": "Required invariants",
        "body": "Keep request_id constant for retries of the same logical order.\nKeep payload unchanged when retrying after 402.\nSend buyer_email always.\nMatch payment network to PAYMENT-REQUIRED; do not hardcode network.\nUse only valid US addresses and one address strategy per party.\nVerify page count and quoted price before payment."
      },
      {
        "title": "Observed failure modes and prevention",
        "body": "422 invalid_type on manual line2:\n\nCause: empty optional fields normalized as null.\nPrevent: omit line2 unless non-empty string.\n\n\nDelay after successful payment (settled_pending_webhook):\n\nCause: settlement acknowledged before webhook reconciliation completes.\nPrevent: poll for up to several minutes with retry/backoff.\n\n\nOccasional non-JSON/transient server response during polling:\n\nCause: temporary upstream/render errors.\nPrevent: parse defensively; if response is non-JSON or 5xx, retry without changing request_id or payload.\n\n\n409 request_id_mismatch:\n\nCause: same request_id reused with modified payload.\nPrevent: generate a new UUID for changed orders; reuse ID only for exact retries."
      },
      {
        "title": "Security Rules",
        "body": "Avoid printing wallet passwords, private keys, or sensitive env vars in logs.\nPrefer encrypted keystore wallets over raw private keys when tooling supports both.\nUse a payment cap (max amount) to avoid accidental overpayment."
      },
      {
        "title": "Operator Output",
        "body": "Return these values after execution:\n\nrequest_id / order_id\nprice/quote summary (including page_count)\npayment settlement details (network, pay_to, settlement_tx, settled_at)\nlatest status (is_paid, current_step)\norder_complete_url when available\n\nReference examples and command snippets:\n\nreferences/payload_templates.md"
      }
    ],
    "body": "PostalForm Machine Order\n\nUse this workflow when an agent needs to send real postal mail (a physical print-and-mail order) reliably on the first attempt.\n\nWorkflow\n1. Collect inputs and choose address strategy\n\nRequire these inputs:\n\nbuyer_name, buyer_email\nsender_name, recipient_name\nPDF source (upload_token, { download_url, file_id }, data URL, or allowed https URL)\nMailing options (double_sided, color, mail_class, certified)\n\nFor each party (sender, recipient), choose exactly one strategy:\n\nManual address: *_address_type: \"Manual\" + *_address_manual\nLoqate address: *_address_type: \"Address\" + *_address_id + *_address_text\n\nDo not mix manual + Loqate for the same party.\n\n2. Build payload with strict idempotency\n\nGenerate a UUID request_id once and keep payload bytes stable across retries.\n\nSet buyer_email every time (required for Stripe receipt routing).\n\nFor manual addresses:\n\nInclude line1, city, state, zip\nInclude line2 only when it has a non-empty string value\nOmit optional fields instead of sending null\n\nUse the tested template in references/payload_templates.md.\n\n3. Preflight with validate endpoint (recommended)\n\nCall:\n\nPOST https://postalform.com/api/machine/orders/validate\n\nIf response is 200, confirm:\n\nquote.page_count matches expected page count\nquote.price_usd and options are acceptable\n\nIf response is 422, fix payload before paying.\n\n4. Create order and settle x402 payment\n\nEndpoint:\n\nPOST https://postalform.com/api/machine/orders\n\nFlow:\n\nSend order payload without payment header.\nReceive 402 with PAYMENT-REQUIRED.\nCreate payment using your wallet stack on the requested network.\nRetry the exact same request body with PAYMENT-SIGNATURE.\nExpect 202 and settlement metadata.\n\nPayment client options:\n\npurl CLI (fastest path when available)\nAny x402-compliant client (@x402/core, @x402/evm, or equivalent custom signer flow)\n\nIf using purl:\n\nPrefer wallet alias/keystore over raw private keys\nUse --password from secure runtime input\nSet a protective --max-amount\nMatch --network to PAYMENT-REQUIRED network\n5. Poll order status until post-payment completion\n\nCall:\n\nGET https://postalform.com/api/machine/orders/:request_id\n\nTreat this as complete when:\n\nis_paid = true\ncurrent_step has advanced through processing (commonly to email_sent)\norder_complete_url is a real URL\n\nHandle transitional state:\n\nstatus: \"settled_pending_webhook\" can persist briefly after on-chain settlement\nContinue polling with backoff; do not resubmit a changed payload under the same request_id\nFirst-Pass Reliability Rules\nRequired invariants\nKeep request_id constant for retries of the same logical order.\nKeep payload unchanged when retrying after 402.\nSend buyer_email always.\nMatch payment network to PAYMENT-REQUIRED; do not hardcode network.\nUse only valid US addresses and one address strategy per party.\nVerify page count and quoted price before payment.\nObserved failure modes and prevention\n422 invalid_type on manual line2:\nCause: empty optional fields normalized as null.\nPrevent: omit line2 unless non-empty string.\nDelay after successful payment (settled_pending_webhook):\nCause: settlement acknowledged before webhook reconciliation completes.\nPrevent: poll for up to several minutes with retry/backoff.\nOccasional non-JSON/transient server response during polling:\nCause: temporary upstream/render errors.\nPrevent: parse defensively; if response is non-JSON or 5xx, retry without changing request_id or payload.\n409 request_id_mismatch:\nCause: same request_id reused with modified payload.\nPrevent: generate a new UUID for changed orders; reuse ID only for exact retries.\nSecurity Rules\nAvoid printing wallet passwords, private keys, or sensitive env vars in logs.\nPrefer encrypted keystore wallets over raw private keys when tooling supports both.\nUse a payment cap (max amount) to avoid accidental overpayment.\nOperator Output\n\nReturn these values after execution:\n\nrequest_id / order_id\nprice/quote summary (including page_count)\npayment settlement details (network, pay_to, settlement_tx, settled_at)\nlatest status (is_paid, current_step)\norder_complete_url when available\n\nReference examples and command snippets:\n\nreferences/payload_templates.md"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/ggaabe/postalform-agent-mailing",
    "publisherUrl": "https://clawhub.ai/ggaabe/postalform-agent-mailing",
    "owner": "ggaabe",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/postalform-agent-mailing",
    "downloadUrl": "https://openagent3.xyz/downloads/postalform-agent-mailing",
    "agentUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent",
    "manifestUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/postalform-agent-mailing/agent.md"
  }
}