Labsco
pdfgate logo

PostalForm MCP

from pdfgate

Mail real letters from agents: PDF → checkout → status.

🔥🔥🔥✓ VerifiedFreeQuick setup
#email#automation#payments#scraping#documents#devops#security#video-editing

Mail API and Remote MCP Server for AI Agents

PostalForm is a mail API and remote MCP server for turning PDFs, letters, forms, and agent output into real physical postal mail. Developers can create reviewable mail drafts, hosted checkout sessions, direct MPP/x402 machine orders, and fulfillment-status lookups without building print, envelope, postage, or carrier-handoff infrastructure.

Quick answer: can developers send postal mail through an API?

Yes. PostalForm lets developers send postal mail through API and MCP workflows. Use hosted-checkout draft tools when a human should review the PDF, addresses, mailing options, and price before payment. Use direct MPP or x402 machine-payment flows only for autonomous runtimes with explicit owner approval, spending limits, and idempotent request IDs.

Developer intent PostalForm path Best default Add a mail API to an app Use the OpenAPI catalog and machine-order REST endpoints Validate first, then create a draft or paid order Let an AI agent prepare physical mail Connect to the remote MCP endpoint at https://postalform.com/mcp Create a hosted-checkout draft Let ChatGPT, Claude, Gemini, Cursor, or Codex use mail tools Register PostalForm as a remote streamable HTTP MCP server Require approval for mail side effects Let an autonomous runtime pay for mail Use postalform.create_machine_order, MPP, or x402 Owner-approved spend limit plus preview review List PostalForm in an MCP or agent registry Use the MCP server card, registry manifest, and this developer page Submit the canonical PostalForm-hosted URLs

Directory-ready summary

Use this table when evaluating PostalForm for an MCP registry, agent directory, API catalog, connector review, or developer-tool listing.

Directory field PostalForm value Product type Physical mail API and remote MCP server Primary endpoint https://postalform.com/mcp Transport Streamable HTTP MCP Human-reviewed default Hosted-checkout draft tools create an unpaid draft and checkout URL so the user can review the PDF, addresses, price, and mailing options before payment Payment-capable path postalform.create_machine_order can use MPP or x402 after explicit owner approval and spend controls No-auth discovery URLs /openapi.json, /apis.json, /.well-known/mcp/server.json, /.well-known/mcp/server-card.json, /.well-known/mcp.json, /.well-known/agent-card.json, /.well-known/x402 Best listing destination https://postalform.com/developers for API/MCP catalogs; https://postalform.com/agents for AI-agent or agent-commerce directories Main use cases Mail PDFs, letters, generated documents, workflow forms, dispute packets, payment notices, and status checks Side-effect boundary Draft tools do not print or mail until checkout is completed. Direct machine orders require a paid MPP/x402 retry Recommended approval policy Require approval before sharing documents, addresses, payment credentials, or sending real mail

Short directory description:

PostalForm is a remote MCP server and physical mail API for creating reviewable print-and-mail drafts from PDFs, letters, and forms, with hosted checkout, fulfillment status, and approved MPP/x402 machine-payment flows.

Which integration surface should you use?

Surface Use it for Avoid it when Hosted checkout via MCP draft tools User-facing assistants, web chat clients, support tools, and workflows where a person should approve payment The agent has already been authorized to pay autonomously ChatGPT Instant Checkout session OpenAI/ChatGPT commerce flows that can render and complete a Stripe-backed checkout session The client cannot use checkout sessions or shared payment tokens Machine-order REST API Server-side integrations, direct validation, quotes, and status polling The user still needs a visual approval step before payment MPP machine payment Agent runtimes that already support MPP challenge/receipt semantics, Stripe Shared Payment Tokens, or card-MPP credentials Simple user-facing flows where hosted checkout is safer x402 machine payment HTTP-native agents and services that can answer 402 Payment Required challenges Workflows without wallet/payment infrastructure or spend controls UCP checkout MCP endpoint Platforms that specifically integrate with the UCP checkout capability Manual-address, letter-text, or workflow-form drafts that need PostalForm MCP tools

Remote MCP discovery

Use these canonical URLs when listing PostalForm in MCP directories, connector catalogs, or agent registries:

The hosted MCP server is best for clients that can connect to a remote streamable HTTP MCP endpoint. Use postalform.create_order_draft, postalform.create_letter_order_draft, and postalform.create_form_order_draft when a human should review and pay in hosted checkout. Use postalform.create_machine_order only when an authorized autonomous runtime should answer an MPP or x402 payment challenge directly.

For the design pattern behind this split, see making physical mail callable from AI agents .

ChatGPT, Gemini, and other MCP clients

PostalForm is ready for clients that can connect to remote MCP servers over streamable HTTP. The same endpoint is used by ChatGPT custom connector-style flows, OpenAI Responses API MCP tools, Gemini SDK MCP sessions, Gemini CLI, Claude, Claude Code, Codex, Cursor, Windsurf, Cline, Replit, OpenClaw, Hermes, n8n, LangChain, and similar MCP clients.

For ChatGPT or OpenAI Responses API integrations, configure PostalForm as a remote MCP server:

{
 "type": "mcp",
 "server_label": "postalform",
 "server_description": "Create real PostalForm mail drafts, hosted checkout sessions, machine-payment mail orders, and order status lookups.",
 "server_url": "https://postalform.com/mcp",
 "require_approval": "always"
}

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

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

For Gemini SDKs, create an MCP client session against the PostalForm endpoint and pass the session tools into Gemini's tool-calling integration. In web-chat clients and user-facing assistant flows, prefer hosted checkout so the user can review the PDF, addresses, price, and mailing options before paying.

UCP (Universal Commerce Protocol)

PostalForm also supports the UCP Checkout capability for platforms that integrate via the UCP MCP binding.

UCP checkout sessions are dynamically priced based on PDF page count and print options. PostalForm expects the PDF and address data in metadata.postalform (pdf can be { download_url, file_id }, { upload_token }, a data URL, or an allowlisted https URL). UCP tool calls must include a platform profile in _meta.ucp.profile.

Note: UCP currently supports PDF-based checkouts with Loqate Address IDs (*_address_type="Address") only. For manual addresses, letter text, and workflow forms, use the PostalForm MCP tools on /mcp.

Example UCP create_checkout:

{
 "name": "create_checkout",
 "arguments": {
 "_meta": {
 "ucp": {
 "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
 }
 },
 "currency": "USD",
 "line_items": [{ "item": { "id": "postalform_mail_pdf_bw_double" }, "quantity": 1 }],
 "payment": {},
 "metadata": {
 "postalform": {
 "pdf": {
 "download_url": "https://example.oaiusercontent.com/file.pdf",
 "file_id": "file_abc123"
 },
 "file_name": "letter.pdf",
 "sender_name": "Sender Example",
 "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
 "sender_address_type": "Address",
 "sender_address_text": "123 Sender St, Springfield, IL 62701",
 "recipient_name": "Recipient Example",
 "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
 "recipient_address_type": "Address",
 "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
 "double_sided": true,
 "color": false
 }
 }
 }
}

Machine payments (x402)

PostalForm supports x402-based machine payments for direct API order creation. The machine payment endpoints are designed for agent runtimes that may not have a PostalForm login or API key: the unpaid create call returns a payment challenge, and the paid retry authorizes the order. Letter payloads can be raw text, HTML, Markdown, or RTF and can include typed or drawn signatures; PostalForm renders the PDF server-side and may return a signed preview URL before payment.

For a crawler-friendly overview of the x402 physical-mail flow, directory fields, and safety defaults, see x402 physical mail API .

  • Create/pay endpoint: POST https://postalform.com/api/machine/orders

  • Validate/quote endpoint (no payment side effects): POST https://postalform.com/api/machine/orders/validate

  • Status endpoint: GET https://postalform.com/api/machine/orders/:id

  • Flow: unpaid request returns 402 + PAYMENT-REQUIRED, client pays and retries with PAYMENT-SIGNATURE, server returns 202 + PAYMENT-RESPONSE

Required request fields for POST /api/machine/orders:

  • request_id (UUID)

  • buyer_name

  • buyer_email (required; set on Stripe PaymentIntent as receipt_email)

  • exactly one document source:

  • pdf (recommended canonical format: { "upload_token": "..." }; also accepts { download_url, file_id }, data URL, or allowlisted https URL)

  • letter (raw string or object with format set to text, html, markdown, or rtf; optional signature as a string or { mode: "typed" | "drawn", text?, dataUrl?, printDataUrl? }; PostalForm renders the PDF server-side)

  • form (workflow form payload discovered through the forms schema endpoints; signature fields accept typed or drawn signature payloads when present)

  • sender/recipient names + addresses (Loqate: *_address_type="Address" + *_address_id + *_address_text, or Manual: *_address_type="Manual" + *_address_manual with { line1, line2?, city, state?, zip, countryCode? }; countryCode defaults to US)

Common options:

  • double_sided (default true)

  • color (default false)

  • mail_class (standard, priority, express)

  • certified (default false)

  • certified_return_receipt (default false; adds Electronic Return Receipt for US Certified Mail; ignored for PinGen registered mail)

  • signature_required (default false; requests USPS signature-on-delivery; ignored for postcards or when mail_class="standard")

  • mailpiece_type (letter or postcard; default letter)

  • postcard_size (4x6, 6x9, 11x6; required when mailpiece_type="postcard")

Postcard machine orders use the same endpoints and payment flow. For postcards, send pdf as the final composed postcard PDF and set mailpiece_type: "postcard" plus postcard_size.

Postcard PDF requirements:

  • Use a 2-page PDF.

  • Page 1 is the artwork side.

  • Page 2 is the mailing side. You can place backside artwork or a non-address message there, but do not place sender/recipient names, return or delivery addresses, indicia, or barcode data in the PDF. PostalForm fills the mailing block automatically.

  • Match the exact bleed canvas for the selected size. The canonical spec and templates live at postcard PDF guidelines :

  • 4x6 template

  • 6x9 template

  • 11x6 template

  • Lob-routed international postcards require postcard_size="4x6" and a U.S. sender/return address. PostalForm routes larger international postcards or international postcards with non-U.S. return addresses to PostGrid before provider submission.

PostalForm normalizes postcard print options server-side to standard mail, full color, double-sided, and no certified/signature add-ons.

MCP endpoint

  • https://postalform.com/mcp

  • Methods: POST/GET/DELETE with the streamable HTTP transport

  • Sessions: initialize once, then include the mcp-session-id header on all subsequent requests

  • Auth: no authentication is required today (contact [email protected] for allowlisting)

  • Transport: JSON-RPC payloads over POST

Payment and checkout

External checkout (any MCP client)

  • Use checkout_url from postalform.create_order_draft to send customers to the hosted PostalForm payment page.

  • Best default for browser-chat MCP clients or any flow where a person should review and pay.

  • Open the URL in a browser (or window.openai.openExternal inside ChatGPT).

  • Poll postalform.get_order_status to confirm payment and fulfillment.

ChatGPT Instant Checkout (Stripe Agentic Commerce)

  • PostalForm returns an ACP checkout_session in the draft response that ChatGPT uses to show Instant Checkout.

  • When the buyer confirms, ChatGPT calls complete_checkout with a Stripe Shared Payment Token (spt_...).

  • Use window.openai.requestCheckout(checkout_session) in your UI.

  • Use checkout_url as a fallback if window.openai.requestCheckout is unavailable.

Direct machine payment (agentic MCP clients)

  • Use postalform.create_machine_order when the agent will pay instead of sending a human to hosted checkout.

  • First call it with payment_protocol="mpp" or "x402" and no payment credential.

  • For MPP, pay one returned WWW-Authenticate: Payment ... challenge with Link CLI, the Link MCP server, Tempo, or a card-MPP client such as Visa's mpp-card/client, then retry the same tool arguments with payment_authorization.

  • For x402, pay the returned PAYMENT-REQUIRED challenge with an x402-compatible wallet/client, then retry the same tool arguments with payment_signature.

  • Reuse the same request_id and order fields on retry.

Tools

  • postalform.list_forms: List published workflow-based forms available to agents.

  • postalform.get_form_schema: Fetch a workflow schema (fields, dependencies, attachments). May include checkout_flow metadata (home or forms_order) for PostalForm web routing; MCP clients/agents can treat this as informational.

  • postalform.create_letter_order_draft: Create a draft order from letter text (server renders a PDF).

  • postalform.create_form_order_draft: Create a draft order from a workflow form JSON submission (server fills template PDF).

  • postalform.create_pdf_upload: Create a short-lived PDF upload URL + upload_token for agents that cannot pass ChatGPT file params. Upload the PDF, then call postalform.create_order_draft with pdf: { upload_token: "..." }.

  • postalform.search_addresses: Search mailing address suggestions. Input: query (min 3 chars), optional country_code (defaults to US), optional container (for drilling into Container results), optional target. Output: address suggestions with ids/text/type/country. If type is Container, call search again with container=id to get Address results for order drafts.

  • postalform.create_order_draft: Create a draft order and receive a checkout URL. Input: pdf (ChatGPT file object { download_url, file_id }, or { upload_token } from postalform.create_pdf_upload, or a data:application/pdf;base64,... URL, or an https URL on an allowlisted host), sender/recipient names, and either Loqate addresses (*_address_type="Address" + *_address_id) or manual addresses (*_address_type="Manual" + *_address_manual, with optional countryCode). Output: order_id, price_usd, checkout_url, checkout_session.

  • postalform.create_machine_order: Create and pay a machine order from a PDF, letter text, or workflow form using direct MPP or x402. Output: payment_required challenge details on the first call, then paid/settled order details after retrying with payment_authorization (MPP) or payment_signature (x402).

  • complete_checkout: Finalize a ChatGPT Instant Checkout session with a payment token. Input: checkout_session_id (order*id), buyer (first_name, last_name optional, email), payment_data.token (Stripe shared payment token, spt*...), provider=stripe. Output: checkout session response with status and order permalink.

  • postalform.get_order_status: Fetch the latest order status details. Input: order_id. Output: found, is_paid, current_step (for example: payment_received, receiver_address_verified, sender_address_verified, pdf_normalized, letter_created, email_sent, canceled, refunded, abandoned).

  • postalform.ping: Health check for the MCP server. Input: none. Output: ping payload for connectivity checks.

Tool payload examples

postalform.list_forms

Request:

{
 "name": "postalform.list_forms",
 "arguments": { "q": "IRS", "limit": 10 }
}

postalform.get_form_schema

Request:

{
 "name": "postalform.get_form_schema",
 "arguments": { "slug": "8822" }
}

Note: the response may include checkout_flow. This is workflow metadata for PostalForm web checkout routing and does not change MCP tool-call sequencing.

postalform.search_addresses

Request:

{
 "name": "postalform.search_addresses",
 "arguments": {
 "target": "recipient",
 "query": "123 Main St"
 }
}

Response:

{
 "structuredContent": {
 "view": "address_suggestions",
 "target": "recipient",
 "query": "123 Main St",
 "suggestions": [
 {
 "id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
 "text": "123 Main St, Springfield, IL 62701",
 "type": "Address",
 "description": ""
 }
 ]
 }
}

postalform.create_letter_order_draft

Request:

{
 "name": "postalform.create_letter_order_draft",
 "arguments": {
 "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "letter": {
 "title": "Payment demand letter",
 "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n",
 "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"
 }
 }
}

postalform.create_form_order_draft

Request:

{
 "name": "postalform.create_form_order_draft",
 "arguments": {
 "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "slug": "8822",
 "fields": {
 "name_line_1": "Sender Example",
 "old_address_line_1": "123 Old St",
 "old_city": "Springfield",
 "old_state": "IL",
 "old_zip": "62701",
 "new_address_line_1": "456 New Ave",
 "new_city": "Springfield",
 "new_state": "IL",
 "new_zip": "62701"
 },
 "sender_name": "Sender Example",
 "sender_address_type": "Address",
 "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
 "sender_address_text": "123 Sender St, Springfield, IL 62701",
 "recipient_name": "IRS",
 "recipient_address_type": "Manual",
 "recipient_address_manual": {
 "line1": "Internal Revenue Service",
 "city": "Kansas City",
 "state": "MO",
 "zip": "64999"
 },
 "use_workflow_recipient": false
 }
}

postalform.create_pdf_upload

Request:

{
 "name": "postalform.create_pdf_upload",
 "arguments": {
 "file_name": "letter.pdf",
 "content_type": "application/pdf",
 "content_length": 1234567
 }
}

Response:

{
 "structuredContent": {
 "upload_url": "https://postalform.com/api/mcp/pdf-uploads/pfu_...",
 "upload_token": "pfu_...",
 "expires_at": "2026-01-17T12:00:00Z",
 "max_bytes": 104857600,
 "required_headers": {
 "Content-Type": "multipart/form-data"
 }
 }
}

Upload the PDF with multipart/form-data using the file field (aliases pdf and pdfFile are also accepted), then pass upload_token to postalform.create_order_draft.

postalform.create_order_draft

Note: pdf accepts a ChatGPT file object, an upload_token, or a base64 data URL (data:application/pdf;base64,...). If you pass a URL, it must be https and hosted on an allowlisted domain (default: *.oaiusercontent.com). Request:

{
 "name": "postalform.create_order_draft",
 "arguments": {
 "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "pdf": { "upload_token": "pfu_..." },
 "file_name": "letter.pdf",
 "sender_name": "Sender Example",
 "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
 "sender_address_type": "Address",
 "sender_address_text": "123 Sender St, Springfield, IL 62701",
 "recipient_name": "Recipient Example",
 "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
 "recipient_address_type": "Address",
 "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
 "double_sided": true,
 "color": false
 }
}

Response:

{
 "structuredContent": {
 "view": "order_draft",
 "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "page_count": 2,
 "price_usd": 2.99,
 "checkout_url": "https://postalform.com/payment?orderId=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "sender_name": "Sender Example",
 "sender_address_text": "123 Sender St, Springfield, IL 62701",
 "recipient_name": "Recipient Example",
 "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
 "checkout_session": {
 "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "payment_provider": {
 "provider": "stripe",
 "merchant_id": "profile_123",
 "supported_payment_methods": ["card", "apple_pay", "google_pay"]
 },
 "status": "ready_for_payment",
 "currency": "usd",
 "line_items": [
 {
 "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "item": { "id": "postalform_mail_pdf", "quantity": 1 },
 "base_amount": 299,
 "discount": 0,
 "subtotal": 299,
 "tax": 0,
 "total": 299
 }
 ],
 "totals": [
 { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
 { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
 { "type": "tax", "display_text": "Tax", "amount": 0 },
 { "type": "total", "display_text": "Total", "amount": 299 }
 ],
 "links": [
 { "type": "terms_of_use", "value": "https://postalform.com/terms" },
 { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
 ],
 "payment_mode": "test"
 }
 }
}

postalform.create_machine_order

First call for an MPP/Link payment challenge:

{
 "name": "postalform.create_machine_order",
 "arguments": {
 "payment_protocol": "mpp",
 "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "buyer_name": "Agent Owner",
 "buyer_email": "[email protected]",
 "letter": {
 "title": "Payment demand letter",
 "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n"
 },
 "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"
 }
 }
}

Response shape:

{
 "structuredContent": {
 "view": "machine_order",
 "protocol": "mpp",
 "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "status": "payment_required",
 "payment": {
 "www_authenticate": ["Payment ..."],
 "retry_header": "Authorization",
 "retry_header_value": "Payment ..."
 }
 }
}

After Link CLI or Link MCP returns the paid MPP credential, retry the same arguments with:

{
 "payment_authorization": "Payment ..."
}

For x402, set payment_protocol to x402; the first response contains payment.payment_required_header, and the retry uses payment_signature.

complete_checkout

Request:

{
 "name": "complete_checkout",
 "arguments": {
 "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "buyer": {
 "first_name": "Jane",
 "last_name": "Doe",
 "email": "[email protected]"
 },
 "payment_data": {
 "token": "spt_test_123",
 "provider": "stripe"
 }
 }
}

Response:

{
 "structuredContent": {
 "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "buyer": {
 "first_name": "Jane",
 "last_name": "Doe",
 "email": "[email protected]"
 },
 "status": "completed",
 "currency": "usd",
 "line_items": [
 {
 "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "item": { "id": "postalform_mail_pdf", "quantity": 1 },
 "base_amount": 299,
 "discount": 0,
 "subtotal": 299,
 "tax": 0,
 "total": 299
 }
 ],
 "fulfillment_options": [
 {
 "type": "shipping",
 "id": "postalform_standard",
 "title": "First Class mail",
 "subtitle": "Mailed via postal carrier",
 "carrier": "Postal carrier",
 "carrier_info": "PostalForm print-and-mail provider",
 "earliest_delivery_time": "2026-07-01T00:00:00.000Z",
 "latest_delivery_time": "2026-07-06T00:00:00.000Z",
 "subtotal": 0,
 "tax": 0,
 "total": 0
 }
 ],
 "fulfillment_option_id": "postalform_standard",
 "totals": [
 { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
 { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
 { "type": "tax", "display_text": "Tax", "amount": 0 },
 { "type": "total", "display_text": "Total", "amount": 299 }
 ],
 "order": {
 "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "permalink_url": "https://postalform.com/order/complete?order_id=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b"
 },
 "messages": [],
 "links": [
 { "type": "terms_of_use", "value": "https://postalform.com/terms" },
 { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
 ]
 }
}

postalform.get_order_status

Response:

{
 "structuredContent": {
 "view": "order_status",
 "found": true,
 "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
 "is_paid": true,
 "current_step": "letter_created"
 }
}

Error response example

{
 "isError": true,
 "content": [
 {
 "type": "text",
 "text": "recipient_address_manual is required when recipient_address_type is Manual."
 }
 ]
}

Integration notes

  • Idempotency: use request_id on draft creation tools (postalform.create_order_draft, postalform.create_letter_order_draft, postalform.create_form_order_draft) and on postalform.create_machine_order. Reuse the same value and same order fields on retries. The server will return the existing draft/order.

  • Errors: tool calls that fail validation return isError=true with a human-readable message. For Instant Checkout, complete_checkout can also return ACP messages with error codes like payment_declined or requires_3ds.

  • Instant Checkout fallback: if window.openai.requestCheckout is unavailable or checkout_session.payment_provider lacks merchant_id, use checkout_url instead.

  • Order status steps: payment_received, receiver_address_verified, sender_address_verified, pdf_normalized, letter_created, email_sent, canceled, refunded, abandoned.

MCP safety, permissions, and rate limits

Treat PostalForm as a real-world action tool because it can create mail drafts and, in machine-payment flows, place paid mail orders after an owner-approved payment challenge. In chat clients, configure the server with require_approval: "always" and require human review before sending user documents, addresses, or payment credentials.

Tool or flow Scope Side effects and limits postalform.list_forms and postalform.get_form_schema Reads the published form catalog and schema metadata No order, file upload, payment, or mail side effect postalform.search_addresses Looks up address suggestions for sender or recipient fields Calls the address-search provider and is IP rate limited. Defaults are 120 searches per minute and 3,000 per day. It does not create an order or payment postalform.create_pdf_upload Creates a short-lived upload URL for a PDF Upload token only. The file still has to be attached to a later draft call. Uploads are limited by the documented page and file-size limits postalform.create_order_draft Creates a hosted-checkout draft from a PDF Creates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed postalform.create_letter_order_draft Renders letter text into a PDF and creates a hosted-checkout draft Creates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed postalform.create_form_order_draft Fills a supported workflow form and creates a hosted-checkout draft Creates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed postalform.create_machine_order Creates or pays a direct MPP/x402 machine order Use only in authorized autonomous runtimes with spend controls. The unpaid call returns a payment challenge; the paid retry must include the MPP authorization or x402 payment signature complete_checkout Completes a ChatGPT Instant Checkout session Use only after the buyer confirms checkout with a Stripe shared payment token postalform.get_order_status and postalform.ping Reads order status or health state No order creation, payment, or mailing side effect

Draft-creating tools and direct machine-order tools are also limited by unpaid-order throttling. The default unpaid-order creation limit is 10 attempts per hour per client IP. On rate limits, MCP tools return an error response and HTTP wrapper calls may return 429.

Security scanners should treat hosted checkout as the default safe path: the tool can create a draft, but the customer still reviews the PDF, addresses, price, and mailing options before payment. Direct machine payment should stay behind explicit owner approval, spending limits, idempotent request_id values, and a preview review step when preview_url is present.

Protocol and platform sources