PostalForm agent skill

PDF, letter, form, postcard and ordinary bulk machine orders return a signed checkout_url, status_url, payment_options, and next_action alongside the 402 challenge. MPP draft tools also return checkout_url. The document, order ID, page count and total stay the same whichever payment option the buyer chooses. Hosted checkout is an alternative to MPP/x402, not an MPP credential type. This fallback does not apply to the separate flower or shipping-label APIs.

1. Review preview_url (or the bulk campaign_url), recipients and total with the buyer. Preserve an uploaded document; do not recreate its contents as a letter to work around an upload problem.
2. If the runtime can actually obtain an approved compatible credential, answer one machine challenge. A connected Link account alone does not establish that the runtime can mint an SPT. Link supports distinct virtual-card, SPT and Link Pay Token integrations; use the capability the runtime exposes.
3. Otherwise present the returned checkout_url. Opening it only reviews the order. Continuing opens Stripe-hosted Checkout and reserves hosted payment for this order; subsequent machine calls return the same checkout option. No wallet setup or CLI installation is required for the buyer.
4. Poll status_url or postalform.get_order_status. payment_authorized means the card was authorized even while is_paid is false. payment_processing and settled_pending_webhook also mean wait, not pay again. payment_review_required needs support reconciliation; closed cannot be paid. Use fulfillment/tracking fields to distinguish printing, mailed and delivered.

Checkout links expire after 24 hours; poll the same order for a fresh link. Concurrent checkout starts reuse a session. A credential rejected before payment (for example, a malformed proof or expired challenge) leaves the same order payable with a corrected credential or hosted checkout. After an interrupted machine payment, retry the same credential and request or poll: a different credential or payment path is blocked while the outcome is uncertain. A 402 response alone does not prove that an earlier attempt failed; a later rejection does not unlock an uncertain payment. Follow the returned payment options and status. A late payment arriving outside the selected checkout is retained for reconciliation and does not trigger another mailing.

No native MCP connection? Use the HTTP create and status endpoints in OpenAPI. Do not switch to browser upload merely because the runtime cannot attach a remote MCP server. See Stripe’s Link integration documentation for agent-owned approval and credential retrieval; PostalForm does not mint credentials from a user’s Link account.

• Remote MCP endpoint: https://postalform.com/mcp
• Transport: streamable HTTP
• Authentication: none required today for the hosted MCP endpoint
• A2A Agent Card: https://postalform.com/.well-known/agent-card.json
• MCP manifest: https://postalform.com/.well-known/mcp.json
• MCP Server Card: https://postalform.com/.well-known/mcp/server-card.json
• MCP Registry server manifest: https://postalform.com/.well-known/mcp/server.json
• OpenAPI: https://postalform.com/openapi.json
• Full developer docs: https://postalform.com/developers
• Autonomous payment guide: https://postalform.com/agents
• MPP-only endpoint guide: https://postalform.com/mpp.md
• MPP mail endpoint guide: https://postalform.com/mpp-mail.md
• MPP flower endpoint guide: https://postalform.com/mpp-flowers.md
• MPP shipping-label endpoint guide: https://postalform.com/mpp-shipping-labels.md
• Open Knowledge Format index: https://postalform.com/okf/index.md

If your client accepts a remote MCP URL, add https://postalform.com/mcp as a streamable HTTP MCP server named postalform.

PostalForm is designed for MCP-capable clients and runtimes including ChatGPT custom connectors or OpenAI Responses API MCP tools, Gemini SDKs, Gemini CLI, Claude, Claude Code, Codex, Cursor, Windsurf, Cline, Replit, OpenClaw, Hermes, n8n, LangChain, and other clients that can connect to a remote streamable HTTP MCP endpoint.

For ChatGPT or OpenAI API flows, configure a remote MCP tool with server_url set to https://postalform.com/mcp. Require approval for tool calls that send document contents, addresses, or payment-related data.

For Gemini CLI, add PostalForm as an HTTP MCP server:

gemini mcp add --transport http postalform https://postalform.com/mcp

For Gemini SDK integrations, connect to the same MCP endpoint with an MCP client session and pass the session tools to the Gemini SDK's MCP/tool-calling integration.

Use these tools to prepare an unpaid draft for buyer review:

• postalform.create_letter_order_draft for a plain letter that PostalForm renders into a printable PDF.
• postalform.create_order_draft for an uploaded PDF or a PDF file URL.
• postalform.list_forms, postalform.get_form_schema, and postalform.create_form_order_draft for supported form workflows.
• postalform.search_addresses when the user wants autocomplete-backed address validation.
• postalform.get_order_status after checkout starts or payment completes.

Use postalform.create_machine_order to prepare a mailing with both a hosted-checkout fallback and an MPP or x402 challenge. Creating without a credential does not pay. Before submitting a credential, obtain the buyer’s approval and respect their spend limit. Retry the same request with the payment credential after the payment client answers the challenge.

For bulk letters, the same tool accepts exactly one of bulk.csv_content or bulk.recipients (JSON address objects with optional merge_fields), plus bulk.content_mode: pdf sends a shared top-level pdf to every recipient, while text/html use bulk.template_text/bulk.template_html with CSV columns or JSON merge fields. Omit top-level recipient fields, letter, form, and postcard options. Review campaign_url, bulk.recipient_count, and the total price_usd before payment. Bulk MPP campaigns can also use postalform.pay_order; fetch its challenge without a credential first, then pay that same order ID. postalform.get_order_status includes the campaign link and per-status counts in bulk.status_counts. See bulk mailing for CSV/JSON examples and payment retries.

All three draft tools accept optional payment_protocol: "mpp" with buyer_email (and optional buyer_name). Draft creation is unpaid: it returns the order ID, PDF preview, total, and payment challenge. Once approved, call postalform.pay_order with order_id and payment_authorization. Omit the credential to refresh the challenge. Payment clients can instead POST {} to the returned payment.endpoint, then retry that endpoint with Authorization: Payment .... Never resubmit the document to pay a prepared draft.

• After buyer approval, a client that obtains a compatible Stripe shared payment token can call complete_checkout with checkout_session.id, buyer details, and payment_data containing provider: "stripe" and the token. Otherwise present the returned checkout_url.
• Retry an interrupted checkout with the same session ID and token. An unverified or processing payment must not prompt another order or replacement payment. Check status and follow the returned messages.
• MPP clients can use the draft-plus-pay_order path or create_machine_order; x402 uses create_machine_order. Show the preview and price, obtain approval, then answer one challenge. Verify the client's actual attachment and payment handoffs before relying on either payment path.
• Never send raw card details to PostalForm. Machine payment paths use MPP, x402, hosted checkout, or Stripe Shared Payment Tokens where applicable.

• PostalForm supports specific destination countries. Validate or quote the order before promising delivery.
• Certified/proof mail covers USPS Certified Mail for qualifying U.S. First Class mail, plus PinGen registered mail for supported European destinations (e.g. Switzerland, France, Belgium).
• Express, Fast, postcard, international, and provider-specific options vary by destination, size, address, and provider eligibility.
• PostalForm does not package or tender parcels. Its MPP-only shipping-label product returns a carrier PDF for a user-supplied parcel; use https://postalform.com/mpp-shipping-labels.md for that distinct flow.
• Do not use PostalForm to mail physical originals, checks, keys, ID cards, or packages, or for notarization, process serving, legal advice, or guaranteed delivery by a specific date.

Ask the user for the document or letter text, sender address, recipient address, and preferred mailing option. Create a draft, show its preview and total for approval, then use compatible Stripe token checkout or present the checkout URL.

Call postalform.create_letter_order_draft with:

{
  "letter": {
    "title": "Payment demand",
    "body": "Hello,\n\nThis is the letter body.\n\nSincerely,\nSender Example",
    "signature": "Sender Example"
  },
  "sender_name": "Sender Example",
  "sender_address_type": "Manual",
  "sender_address_manual": {
    "line1": "123 Sender St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62701"
  },
  "recipient_name": "Recipient Example",
  "recipient_address_type": "Manual",
  "recipient_address_manual": {
    "line1": "456 Recipient Ave",
    "city": "Springfield",
    "state": "IL",
    "zip": "62701"
  }
}

Present the prepared draft and total for buyer approval. Then use complete_checkout if the client supplies a compatible Stripe token, or return checkout_url for hosted payment.

• https://postalform.com/llms.txt
• https://postalform.com/llms-full.txt
• https://postalform.com/ai.md
• https://postalform.com/developers.md
• https://postalform.com/agents.md
• https://postalform.com/mpp.md
• https://postalform.com/mpp-mail.md
• https://postalform.com/mpp-flowers.md
• https://postalform.com/mpp-shipping-labels.md
• https://postalform.com/pricing-calculator.md
• https://postalform.com/okf/index.md