PostalForm MCP Server

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

View on postalform.com

Documentation

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 intentPostalForm pathBest default
Add a mail API to an appUse the OpenAPI catalog and machine-order REST endpointsValidate first, then create a draft or paid order
Let an AI agent prepare physical mailConnect to the remote MCP endpoint at https://postalform.com/mcpCreate a hosted-checkout draft
Let ChatGPT, Claude, Gemini, Cursor, or Codex use mail toolsRegister PostalForm as a remote streamable HTTP MCP serverRequire approval for mail side effects
Let an autonomous runtime pay for mailUse postalform.create_machine_order, MPP, or x402Owner-approved spend limit plus preview review
List PostalForm in an MCP or agent registryUse the MCP server card, registry manifest, and this developer pageSubmit 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 fieldPostalForm value
Product typePhysical mail API and remote MCP server
Primary endpointhttps://postalform.com/mcp
TransportStreamable HTTP MCP
Human-reviewed defaultHosted-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 pathpostalform.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 destinationhttps://postalform.com/developers for API/MCP catalogs; https://postalform.com/agents for AI-agent or agent-commerce directories
Main use casesMail PDFs, letters, generated documents, workflow forms, dispute packets, payment notices, and status checks
Side-effect boundaryDraft tools do not print or mail until checkout is completed. Direct machine orders require a paid MPP/x402 retry
Recommended approval policyRequire 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?

SurfaceUse it forAvoid it when
Hosted checkout via MCP draft toolsUser-facing assistants, web chat clients, support tools, and workflows where a person should approve paymentThe agent has already been authorized to pay autonomously
ChatGPT Instant Checkout sessionOpenAI/ChatGPT commerce flows that can render and complete a Stripe-backed checkout sessionThe client cannot use checkout sessions or shared payment tokens
Machine-order REST APIServer-side integrations, direct validation, quotes, and status pollingThe user still needs a visual approval step before payment
MPP machine paymentAgent runtimes that already support MPP challenge/receipt semantics or Stripe Shared Payment TokensSimple user-facing flows where hosted checkout is safer
x402 machine paymentHTTP-native agents and services that can answer 402 Payment Required challengesWorkflows without wallet/payment infrastructure or spend controls
UCP checkout MCP endpointPlatforms that specifically integrate with the UCP checkout capabilityManual-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 private preview)

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)
  • 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:
  • 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

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.
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 or the Link MCP server, 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": "2025-01-01T00:00:00.000Z",
        "latest_delivery_time": "2025-01-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.

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.
  • 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.
  • Address suggestions can include type="Container" (buildings/complexes). Call postalform.search_addresses again with container=<id> 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 flowScopeSide effects and limits
postalform.list_forms and postalform.get_form_schemaReads the published form catalog and schema metadataNo order, file upload, payment, or mail side effect
postalform.search_addressesLooks up address suggestions for sender or recipient fieldsCalls 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_uploadCreates a short-lived upload URL for a PDFUpload 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_draftCreates a hosted-checkout draft from a PDFCreates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed
postalform.create_letter_order_draftRenders letter text into a PDF and creates a hosted-checkout draftCreates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed
postalform.create_form_order_draftFills a supported workflow form and creates a hosted-checkout draftCreates an unpaid draft and checkout URL. No printing or mailing happens until checkout is completed
postalform.create_machine_orderCreates or pays a direct MPP/x402 machine orderUse 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_checkoutCompletes a ChatGPT Instant Checkout sessionUse only after the buyer confirms checkout with a Stripe shared payment token
postalform.get_order_status and postalform.pingReads order status or health stateNo 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

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 [email protected].
  • 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.