Developers
Mail Letters With an API
PostalForm lets an app or AI assistant prepare a reviewable physical-mail draft from text, HTML, Markdown, RTF, or PDF. This guide covers the hosted-checkout and remote MCP paths, where a person can inspect the printable document, addresses, mailing options, and price before payment makes the mailing real.
Published Jan 20, 2026 • Updated Aug 31, 2026
Need persistent API keys, a free simulated test environment, prepaid credits, and signed webhooks? Start with the PostalForm Projects developer mail API.
Direct answer: can I mail letters with an API?
Yes. PostalForm's hosted-checkout and MCP tools can create a letter draft, render a PDF preview, collect addresses and options, and return a checkout URL. Nothing is printed or mailed until the sender reviews and pays. For a conventional server-side REST integration with workspace API keys, use PostalForm Projects instead.
Hosted-checkout and MCP paths
| Starting point | PostalForm path | Best default |
|---|---|---|
| Plain text letter | Create a letter draft and render a PDF preview | Hosted checkout |
| HTML or Markdown | Render server-side into a printable letter PDF | Hosted checkout with preview |
| RTF document | Convert rich-text content into the mailpiece PDF | Hosted checkout with preview |
| Existing PDF | Upload the PDF, then create a reviewable mail draft | Hosted checkout |
| Agent-generated letter | Call the remote MCP draft tool and return its checkout URL | Require approval before payment |
Use PostalForm Projects when your server needs persistent test/live API keys, free simulated fulfillment, final-price quotes, idempotent order creation, prepaid credits, and signed webhooks. Use x402 or MPP machine payment only for an approved autonomous runtime with an explicit spend limit.
Hosted-checkout flow for letters
- Create the letter content - Send text, HTML, Markdown, RTF, or an uploaded PDF.
- Provide addresses - Use sender and recipient address fields or supported address IDs.
- Choose options - Set available print and mailing options such as color, duplex, speed, or Certified Mail when eligible.
- Show the preview - Let the sender inspect the rendered PDF before payment.
- Launch checkout - Use the returned checkout URL for review and payment.
- Track status - Poll the order status after checkout completes.
Remote MCP flow for AI assistants
PostalForm's remote MCP server is available at https://postalform.com/mcp. A compatible client can search addresses, create a draft from letter text or an uploaded PDF, and return a checkout_url for human review and payment.
- Initialize a streamable HTTP MCP session.
- Search or provide the sender and recipient addresses.
- Call the letter- or PDF-draft tool.
- Show the returned preview and checkout URL to the user.
- Require approval before opening checkout or completing payment.
- Poll the order-status tool after payment.
See the MCP developer guide for connection details, tool names, payload examples, payment choices, and current limits.
Good fits for mailing letters by API
| Use case | Why PostalForm fits |
|---|---|
| Invoices and statements | Generate or upload a letter, show the preview, and send through checkout. |
| Notices and demand letters | Keep human review before the mailpiece becomes real postal mail. |
| Customer support mail | Let internal tools create drafts without asking staff to print envelopes. |
| Case-management workflows | Trigger reviewable letters from case records or form submissions. |
| AI assistant actions | Let an agent prepare a letter while preserving review and payment approval. |
| Certified Mail workflows | Request eligible proof options when the route and mailpiece support them. |
How PostalForm differs from direct-mail campaign APIs
Many letter-mail APIs are built for broad campaign automation, postcards, CRM sequences, or enterprise transactional mail. PostalForm is focused on reviewable document mail: letters, PDFs, forms, dispute packets, hosted checkout, and agent-created mail with explicit approval guardrails.
| Need | Compare first |
|---|---|
| Reviewable letter drafts from text, HTML, Markdown, RTF, or PDFs | PostalForm |
| High-volume transactional print-mail infrastructure | Lob or PostGrid |
| CRM-triggered marketing campaigns | Postalytics or a marketing automation platform |
| Broad self-service print-to-mail catalog | Click2Mail |
| Real-estate investor letter sequences | Real-estate direct-mail platforms |
Safety defaults for letter APIs
Physical mail has offline consequences. A letter API should not behave like a normal email API where retries and automation are harmless.
- Prefer hosted checkout when a human can review and pay.
- Show the rendered PDF preview before payment.
- Use idempotent request IDs for any direct-payment flow.
- Require explicit owner approval before MPP or x402 payment.
- Do not use PostalForm to send spam, harassment, illegal content, or mail the sender is not authorized to send.
- Follow the applicable recipient, agency, contract, or legal-notice instructions; PostalForm does not provide legal advice.
Sources
FAQs
- Do you offer an API for mailing letters?
- Yes. PostalForm supports hosted-checkout and MCP draft flows, while PostalForm Projects provides persistent REST API keys, test mode, quotes, orders, and webhooks.
- Can I create a letter from text instead of uploading a PDF?
- Yes. Supported workflows can create letters from text, HTML, Markdown, or RTF, then render a printable PDF preview.
- Can an AI agent mail a letter?
- Yes, but hosted checkout is the safest default. The agent can create the draft and preview, then a human can review and pay.
- Can I control print options?
- Yes. PostalForm supports options such as color, duplex, delivery speed, and Certified Mail where eligible.
- Does the API send the letter immediately?
- Hosted-checkout drafts do not send mail until the sender pays. Direct machine-payment orders should be reserved for approved runtimes with spend controls and idempotent request IDs.
- Is this a direct-mail marketing API?
- PostalForm can support bulk and developer workflows, but it is not a CRM campaign suite. It is strongest for document and letter workflows that need review before physical mailing.
- Does PostalForm provide legal advice for mailed letters?
- No. PostalForm helps create and mail letters, but it does not decide whether a letter is legally sufficient.
Ready to send it?
For a human-reviewed or agent-assisted flow, start with the MCP and hosted-checkout examples.