--- title: Mail API and Remote MCP Server for AI Agents description: 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. seotitle: Mail API and Remote MCP Server for AI Agents | PostalForm seo-description: Use PostalForm as a physical mail API and remote MCP server. Create reviewable mail drafts, hosted checkout sessions, MPP/x402 machine orders, and fulfillment-status tools. group: resources indexable: true nav: true schema: webpage eyebrow: Developers published: 2026-01-15T12:29:58-06:00 updated: 2026-06-17 path: /developers --- # 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: ```text 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: - Remote MCP endpoint: https://postalform.com/mcp - A2A Agent Card: https://postalform.com/.well-known/agent-card.json - A2A JSON-RPC discovery bridge: https://postalform.com/a2a - MCP server card: https://postalform.com/.well-known/mcp/server-card.json - MCP compatibility manifest: https://postalform.com/.well-known/mcp.json - MCP Registry server manifest: https://postalform.com/.well-known/mcp/server.json - Agent skill: https://postalform.com/skill.md - LLM overview: https://postalform.com/llms.txt - Full LLM content dump: https://postalform.com/llms-full.txt - Open Knowledge Format index: https://postalform.com/okf/index.md - APIs.json index: https://postalform.com/apis.json - API catalog: https://postalform.com/.well-known/api-catalog - API specification: https://postalform.com/openapi.json - Agent guide: https://postalform.com/agents - AI instructions: https://postalform.com/ai 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](/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: ```json { "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: ```bash 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. - Discovery profile: https://postalform.com/.well-known/ucp - UCP MCP endpoint: https://postalform.com/ucp/mcp - Capability: dev.ucp.shopping.checkout (version 2026-01-11) - Tools: create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout 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: ```json { "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](/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`; `settled_pending_webhook` means Stripe is still verifying the settlement, so poll the status endpoint rather than paying again 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` (single-mailpiece workflow form payload discovered through the machine forms schema endpoints; signature fields accept typed or drawn signature payloads when present; statutory multi-recipient workflows are excluded and remain web-only) - 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`; both address modes accept only the checkout-supported country codes `US`, `CA`, `AT`, `BE`, `CH`, `DE`, `ES`, `FR`, `GB`, `IN`, `LU`, and `NL`) Common options: - `double_sided` (default `true`) - `color` (default `false`) - `mail_class` (`standard`, `priority`, `express`) - `certified` (default `false`) - `certified_return_receipt` (default `false`; adds a return receipt for US Certified Mail; ignored for PinGen registered mail) - `return_receipt_format` (`electronic` by default, or `physical` for the mailed PS Form 3811 green card; requires `certified_return_receipt=true`) - `restricted_delivery` (default `false`; requests addressee-only USPS Restricted Delivery and requires `certified_return_receipt=true`) - `err_delivery` (`manual` by default, or `email` to have PostalForm acquire and email the signed electronic receipt) - `err_email` (optional override for automatic delivery; defaults to `buyer_email` when omitted) - `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](/postcard-pdf-guidelines): - [4x6 template](/postcard-guidelines/us_intl_postcard_6inx4in.pdf) - [6x9 template](/postcard-guidelines/us_intl_postcard_9inx6in.pdf) - [11x6 template](/postcard-guidelines/us_intl_postcard_11inx6in.pdf) - 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 support@postalform.com for allowlisting) - Transport: JSON-RPC payloads over POST ## Integration quickstart 1. Point your MCP client at /mcp and initialize a session. 2. Choose addresses: use Loqate IDs via `postalform.search_addresses`, or use manual addresses with `*_address_type="Manual"` + `*_address_manual` (`countryCode` defaults to `US`). 3. Create a draft: - Letter text: `postalform.create_letter_order_draft` (recommended for ChatGPT apps). - Workflow forms: `postalform.list_forms` -> `postalform.get_form_schema` -> `postalform.create_form_order_draft`. - PDF upload: `postalform.create_order_draft` (ChatGPT file params, `upload_token`, data URL, or allowlisted https URL). 4. Choose the payment path: - Official ChatGPT or Claude web chat UIs: send the customer to `checkout_url`, or use `checkout_session` for ChatGPT Instant Checkout. - Autonomous runtimes such as Codex, Claude Code, OpenClaw, or Hermes: call `postalform.create_machine_order`, pay the returned MPP or x402 challenge with Link CLI/Link MCP or an x402 wallet client, then retry the same tool call with the payment credential. 5. Poll order status as fulfillment progresses. ```js import { Client } from '@modelcontextprotocol/sdk/client/index.js' import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js' const transport = new StreamableHTTPClientTransport(new URL('https://postalform.com/mcp')) const client = new Client({ name: 'my-agent', version: '1.0.0' }) await client.connect(transport) await client.listTools() const draft = await client.callTool({ name: 'postalform.create_letter_order_draft', arguments: { letter: { title: 'Demand for payment', body: 'Hello...\\n\\nThis is my 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', }, }, }) console.log(draft.structuredContent?.checkout_url) ``` ## 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 supported single-mailpiece workflow forms available to agents. Coordinated statutory multi-recipient workflows remain web-only. - `postalform.get_form_schema`: Fetch a supported single-mailpiece workflow schema (fields, dependencies, attachments). The machine schema caps inline attachment files and reports `attachments_max_total_size_mb` (currently 12 MB combined after base64 decoding). 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 supported single-mailpiece workflow JSON submission; the server fills a form, renders a letter, or assembles required uploaded packet documents according to the discovered schema. Inline workflow attachments are limited to 12 MB combined after base64 decoding even when the browser upload workflow permits larger files. - `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). A paid crypto retry can briefly return `settled_pending_webhook`; poll status and do not pay again. - `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: ```json { "name": "postalform.list_forms", "arguments": { "q": "IRS", "limit": 10 } } ``` ### postalform.get_form_schema Request: ```json { "name": "postalform.get_form_schema", "arguments": { "slug": "1099-nec" } } ``` 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: ```json { "name": "postalform.search_addresses", "arguments": { "target": "recipient", "query": "123 Main St" } } ``` Response: ```json { "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: ```json { "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: ```json { "name": "postalform.create_form_order_draft", "arguments": { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "slug": "1099-nec", "fields": { "calendar_year": "2025", "payer_name": "Sender Example LLC", "payer_street_address": "123 Sender St", "payer_city_state_zip_phone": "Springfield, IL 62701, 217-555-0100", "payer_tin": "12-3456789", "recipient_tin": "123-45-6789", "recipient_name": "Contractor Example", "recipient_street_address": "456 Recipient Ave", "recipient_city_state_zip": "Springfield, IL 62701", "box_1_nonemployee_compensation": "1250.00" }, "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": "Contractor Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "city": "Springfield", "state": "IL", "zip": "62701" } } } ``` ### postalform.create_pdf_upload Request: ```json { "name": "postalform.create_pdf_upload", "arguments": { "file_name": "letter.pdf", "content_type": "application/pdf", "content_length": 1234567 } } ``` Response: ```json { "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: ```json { "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: ```json { "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: ```json { "name": "postalform.create_machine_order", "arguments": { "payment_protocol": "mpp", "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "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: ```json { "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: ```json { "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: ```json { "name": "complete_checkout", "arguments": { "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "payment_data": { "token": "spt_test_123", "provider": "stripe" } } } ``` Response: ```json { "structuredContent": { "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "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: ```json { "structuredContent": { "view": "order_status", "found": true, "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "is_paid": true, "current_step": "letter_created" } } ``` ### Error response example ```json { "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`. ## Limits and requirements - All orders are printed from PDFs. For `postalform.create_order_draft` you supply the PDF. For `postalform.create_letter_order_draft` and `postalform.create_form_order_draft` PostalForm generates the PDF server-side. PDFs are sanitized before printing. - Inline `form.attachments` are base64 JSON and may total at most 12 MB after decoding. Follow each attachment's `allowed_types`, `max_files`, and machine-capped `max_size_mb` values from the workflow schema. - For a workflow with `recipient.mode="user"`, the top-level recipient name/address controls the envelope. Keep it aligned with recipient address-role fields in `form.fields`; those fields do not override the top-level machine-order address. - Max 199 pages and 100 MB per file. - `download_url` must be HTTPS and hosted on an allowlisted domain (ChatGPT attachments use `oaiusercontent.com` by default). The URL must be publicly reachable without auth headers. If you cannot provide an allowlisted URL, use `postalform.create_pdf_upload` to get an `upload_token`, or pass a `data:application/pdf;base64,...` URL instead. - Address countries default to `US` when omitted. Use Loqate address ids returned by `postalform.search_addresses` (the id prefix carries the country), or use manual address input with `*_address_type="Manual"` and `*_address_manual.countryCode`. Machine orders enforce the same country list as the checkout address picker: `US`, `CA`, `AT`, `BE`, `CH`, `DE`, `ES`, `FR`, `GB`, `IN`, `LU`, and `NL`; unsupported or invalid codes are rejected. Bulk CSVs accept the same list through `country`, `country_code`, or `countrycode`. - Address suggestions can include `type="Container"` (buildings/complexes). Call `postalform.search_addresses` again with `container=` and a refined query (suite, unit, PO Box) to get `type="Address"` results. Only `type="Address"` (not Container) is valid for Loqate-based order drafts. ## 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 - [OpenAI remote MCP and connectors](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) - [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/getting-started/intro) - [Google Gemini MCP tools](https://ai.google.dev/gemini-api/docs/function-calling#model-context-protocol-mcp) - [Stripe Machine Payments Protocol](https://stripe.com/blog/machine-payments-protocol) - [x402 payment protocol](https://www.x402.org/) ## FAQs - **Is PostalForm a mail API?** Yes. PostalForm exposes machine-order REST endpoints, an OpenAPI catalog, and a remote MCP server for creating physical-mail drafts, quotes, machine-payment orders, and fulfillment-status lookups. - **Can an MCP server send real postal mail?** Yes, but PostalForm separates draft creation from paid mailing. Draft tools create an unpaid hosted-checkout draft; direct machine-order tools should be used only by authorized runtimes with spending controls and approval. - **What is the safest default for ChatGPT, Claude, Gemini, Cursor, or Codex?** Use the remote MCP endpoint at https://postalform.com/mcp, configure approval for mail side effects, create a hosted-checkout draft, and let the user review the PDF, addresses, price, and options before payment. - **Can an agent pay for mail with x402 or MPP?** Yes. PostalForm supports direct machine-payment flows for authorized autonomous runtimes. The unpaid call returns a payment challenge, and the paid retry must include the x402 payment signature or MPP authorization. - **Do I need a PostalForm API key?** Not for the current public MCP endpoint or machine-payment flow. Some high-volume, abuse-sensitive, or allowlisted deployments may require coordination with support@postalform.com. - **Can I upload PDFs through the API or MCP?** Yes. Use the PDF upload tool to create a short-lived upload token, pass an allowlisted HTTPS download URL, use a ChatGPT attachment URL, or provide a data URL where supported. - **How do I keep mail side effects safe?** Treat physical mail as a real-world action. Use hosted checkout by default, require human approval, set spend limits, reuse idempotency request IDs, and review preview URLs before payment when present.