Developers
x402 physical mail API
PostalForm exposes an x402 physical mail API for agents and software that need to turn a PDF, letter, form packet, postcard, or flower-card workflow into real-world fulfillment. The safe pattern is to validate and preview the mailpiece before payment, then use x402 only when an autonomous runtime has explicit owner approval, a spend limit, and an idempotent request ID.
Published May 31, 2026
Quick answer: can x402 pay for physical mail?
Yes. PostalForm supports x402 for physical mail orders through HTTP 402 Payment Required challenge and retry flows. An agent can validate the payload, receive pricing and eligibility feedback, create an unpaid machine order, answer the x402 payment challenge, retry with the payment signature, and then poll fulfillment status.
Use hosted checkout instead when a person should review the PDF, addresses, mailing options, and price before payment.
x402 mail flow
| Step | Endpoint or action | Side effect | Best practice |
|---|---|---|---|
| Discover | GET /.well-known/x402 |
No order | Read resources, pricing mode, network, OpenAPI, and docs links |
| Validate | POST /api/machine/orders/validate |
No order | Check document source, addresses, options, and quote before payment |
| Create unpaid order | POST /api/machine/orders without payment |
Unpaid draft/payment challenge | Reuse the same request_id if retrying |
| Pay and retry | Same POST /api/machine/orders with x402 payment |
Paid machine order | Send only after owner-approved spend policy is satisfied |
| Track | GET /api/machine/orders/:id |
No new mail action | Poll fulfillment status after payment |
PostalForm also exposes dedicated x402 flower-letter endpoints for agents that need to send flowers with a short card note. Use the flower-letter endpoints for that product instead of the document-mail endpoints.
x402 endpoints for PostalForm
| Use case | Validate | Create/pay | Status |
|---|---|---|---|
| PDF, letter, form, postcard, or bulk mail | POST /api/machine/orders/validate |
POST /api/machine/orders |
GET /api/machine/orders/:id |
| Flower letter with card note | POST /api/machine/flower-letters/validate |
POST /api/machine/flower-letters |
GET /api/machine/flower-letters/:id |
The machine order payload can start from one document source: an uploaded PDF, a hosted PDF URL when allowed, raw letter text, HTML, Markdown, RTF, or a supported workflow form payload. For document mail, PostalForm can return a preview URL when server-side rendering is available so the owner or supervising process can inspect the output before payment.
x402 vs hosted checkout vs MPP
| Payment path | Best for | Human review default | Notes |
|---|---|---|---|
| Hosted checkout | Chat assistants, support tools, consumer flows, and legal/dispute workflows | Required before payment | Lowest-risk default because payment happens in PostalForm checkout |
| x402 | HTTP-native agents that can answer 402 Payment Required challenges |
Recommended before direct payment | Good for service-to-service calls where no PostalForm account or API key is desired |
| MPP | Runtimes that already support Stripe machine-payment semantics, Tempo, or Stripe Shared Payment Tokens | Recommended before direct payment | Similar authorization boundary, different challenge and credential format |
For physical mail, x402 is a payment protocol, not a product-policy substitute. The integration still needs a clear answer to who authorized the spend, what documents can be mailed, which recipients are allowed, and how duplicate retries are prevented.
Directory and crawler fields
Use these canonical fields for x402 directories, agent registries, and API crawlers:
| Field | Value |
|---|---|
| Service name | PostalForm |
| Service base URL | https://postalform.com |
| x402 discovery URL | https://postalform.com/.well-known/x402 |
| OpenAPI URL | https://postalform.com/openapi.json |
| API catalog | https://postalform.com/.well-known/api-catalog |
| Agent guide | https://postalform.com/agents |
| Developer docs | https://postalform.com/developers |
| LLM overview | https://postalform.com/llms.txt |
| Best description | x402-enabled physical-mail API for reviewable print-and-mail orders, validation before payment, hosted checkout fallback, MCP, MPP, and fulfillment status |
Guardrails for x402 mail
- Validate first. Do not pay before checking payload, address, mailpiece, and quote details.
- Use a stable
request_idso retries do not create duplicate mail orders. - Show a PDF preview when available before answering a payment challenge.
- Enforce spend limits outside the model prompt, not only in natural-language instructions.
- Keep hosted checkout as the default for user-facing assistants.
- Do not use PostalForm to send spam, harassment, illegal content, or documents the sender is not authorized to mail.
- Remember that physical mail is a real-world side effect: after payment and provider processing, the mailpiece enters a print, envelope, postage, routing, and carrier-handoff workflow.
Sources
FAQs
- Does PostalForm use x402 for real postal mail?
- Yes. PostalForm uses x402 for approved machine-order flows where an agent or software client validates a physical-mail payload, receives a 402 payment challenge, pays, retries, and then tracks fulfillment.
- Do I need a PostalForm API key for x402?
- Not for the current public machine-payment flow. The x402 payment challenge is the authorization boundary, though high-volume or abuse-sensitive integrations may require coordination with PostalForm.
- Should ChatGPT or Claude use x402 by default?
- No. Chat-style assistants should usually create a hosted-checkout draft so the user can review the PDF, addresses, options, and price before payment.
- Can I send a PDF with x402?
- Yes. Use the machine order endpoints with a supported PDF source, or create an upload token when a direct file URL is not suitable.
- Can x402 mail orders include letters generated from text?
- Yes. PostalForm can render supported text, HTML, Markdown, or RTF letter content into a printable PDF before the mail order is paid.
- How do agents avoid duplicate mailings?
- Use an idempotent request_id and retry the same request body after the 402 challenge. Do not create a new request ID for the payment retry.
- Is x402 the same as MPP?
- No. PostalForm supports both, but x402 uses HTTP 402 payment challenge/retry semantics while MPP uses a different machine-payment challenge and credential format.