Print and mail real letters and postcards via API — pay per order with crypto or Stripe.
What it does
PostalForm's MPP machine endpoint lets AI agents programmatically create print-and-mail orders for US letters and postcards. You POST a JSON payload containing a PDF reference (upload token, download URL, or base64), sender/recipient addresses (verified via Loqate or manual entry), and mailing options (double-sided, color, mail class, certified). The server returns a 402 MPP challenge with two settlement methods: Tempo (pathUSD on chain 4217) and Stripe (card/link). After settling payment and replaying the request with an Authorization: Payment header, the order is accepted for printing and USPS mailing. A separate validate endpoint lets you pre-check payloads and get a price quote without triggering payment.
Bulk mailing campaigns are also supported. Instead of a single recipient, supply a `bulk` object with CSV recipient data and a content mode (text with merge fields, HTML with merge fields, or a single PDF for all rows). The validate response returns the recipient count and content mode. After payment, poll the status endpoint until the order reaches its terminal state; bulk orders include a campaign_url for per-recipient tracking.
Pricing ranges from $3.40 to $200.00 per order depending on page count, color, mail class, and add-ons like Certified Mail. The base fee is $3.00, with $0.20/page B&W or $0.40/page color, plus flat-fee tiers for high page counts. Postcards are supported in 4×6, 6×9, and 11×6 sizes with specific PDF bleed templates. The endpoint uses request_id as a strict idempotency key — reuse the same ID and body on payment retries, but generate a fresh UUID for genuinely new orders.
Capabilities
Use cases
- —AI agent sends a legal demand letter or dispute packet on behalf of a user
- —Automated bulk outreach campaign mailing personalized letters to a CSV list
- —Programmatic certified mail delivery with return receipt tracking
- —Agent-driven postcard marketing campaigns
- —Mailing IRS forms or government documents without a printer
Fit
Best for
- —AI agents that need to bridge digital workflows to physical US mail
- —Developers building automated document-mailing pipelines
- —Bulk direct-mail campaigns with merge-field personalization
- —Sending certified or express USPS mail programmatically
Not for
- —International mail (addresses must be US-based per schema)
- —Sub-second latency use cases — physical mail has multi-day fulfillment
- —Free or zero-cost mailing — every order has a minimum ~$3.40 charge
Quick start
curl -X POST https://postalform.com/api/machine/mpp/orders/validate \
-H 'Content-Type: application/json' \
-d '{
"request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
"buyer_name": "Agent Owner",
"buyer_email": "owner@example.com",
"pdf": { "upload_token": "pfu_123" },
"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" },
"double_sided": true, "color": false, "mail_class": "standard"
}'Example
Request
{
"pdf": {
"upload_token": "pfu_123"
},
"color": false,
"certified": false,
"file_name": "letter.pdf",
"buyer_name": "Agent Owner",
"mail_class": "standard",
"request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
"buyer_email": "owner@example.com",
"sender_name": "Sender Example",
"double_sided": true,
"recipient_name": "Recipient Example",
"sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
"sender_address_text": "123 Sender St, Springfield, IL 62701",
"sender_address_type": "Address",
"recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
"recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
"recipient_address_type": "Address"
}Response
{
"bulk": null,
"quote": {
"color": false,
"currency": "usd",
"provider": "postalform",
"certified": false,
"price_usd": 3.4,
"mail_class": "standard",
"page_count": 1,
"double_sided": true,
"postcard_size": null,
"full_price_usd": 3.4,
"mailpiece_type": "letter",
"billable_page_count": 1
},
"status": "validated_new_order",
"order_id": null,
"request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
"request_hash": "abc123def456",
"postcard_guidelines_url": null
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, multiple examples, clear pricing info, and a live 402 MPP challenge confirming the endpoint is operational. Docs are thorough including bulk, postcard, and idempotency guidance. Minor gap: no actual 200/202 response example was captured from a real paid order.
Warnings
- —US addresses only — sender_address_id pattern requires ^US| prefix
- —Stripe challenge amount is 340 cents ($3.40 USD); Tempo challenge amount is 3400000 base units (pathUSD with 6 decimals = $3.40 USD) — both are discovery-probe minimums, actual prices vary by order
Citations
- —Pricing starts at $3.00 base fee, $0.20/page B&W, $0.40/page color, with flat-fee tiers for high page countshttps://postalform.com/pricing
- —Endpoint returns 402 with WWW-Authenticate: Payment challenges for tempo and stripe methodshttps://postalform.com/api/machine/mpp/orders
- —Price range $3.40–$200.00 per order as declared in x-payment-infohttps://postalform.com
- —Supports bulk mailing with CSV content, text/html/pdf content modes, and merge fieldshttps://postalform.com
- —Postcard sizes 4x6, 6x9, 11x6 supported with specific PDF bleed templateshttps://postalform.com
- —MCP server available at /mcp for Stripe Agentic Commerce / ChatGPT integrationhttps://postalform.com/docs
- —Certified Mail available for First Class only with optional electronic return receipthttps://postalform.com/pricing