LetterAPI Documentation
LetterAPI lets you send physical postal letters via a simple REST API. One POST request — we handle printing, folding, stamping, and delivery via Canada Post or USPS.
Base URL — All API requests go to
Quick start
Authentication
All requests must include your API key in the
| Key type | Prefix | Behavior |
|---|---|---|
| Live key | ltr_live_ | Real letters are printed and mailed. Billing applies. |
| Dev key | ltr_dev_ | PDFs are generated but never mailed. Max 3 addresses per call. No charge. |
Keep your key secret. Never expose it in client-side code or public repositories. Use environment variables.
Dev mode
Use your dev API key to test your integration without sending real letters or incurring charges.
| Behavior | Live | Dev |
|---|---|---|
| PDFs generated | ✓ | ✓ |
| Letters mailed | ✓ | ✗ |
| Billing applied | ✓ | ✗ |
| Max addresses per call | Unlimited | 3 |
| Order status | printing | dev |
Errors
All errors return a JSON object with an
| Status | Meaning |
|---|---|
| 201 | Order created successfully. |
| 400 | Missing or invalid parameters. Check |
| 401 | Missing or invalid API key. |
| 404 | Template not found, or your account doesn't have access to it. |
| 500 | Internal server error. Contact support if this persists. |
Send mail
Create an order and trigger letter generation. Each address in the
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| templateToken | string | required | The token of the letter template to use. Provided by LetterAPI when a template is created for your account. |
| fields | object | required | Key-value pairs of dynamic content to inject into the template. Keys depend on the template definition. |
| addresses | object | required | A map of arbitrary keys to address strings. Each entry produces one letter. Max 3 in dev mode. |
Example request
Response
Example — Python
Example — PHP
List orders
Returns all orders for the authenticated account, sorted by most recent first.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | string | optional | Filter to a specific order by its token. Returns 404 if not found. |
Response
Get order
Retrieve a single order by token. Useful for checking status and accessing generated PDFs.
This is the same
Order statuses
| Status | Meaning |
|---|---|
| pending | Order received, PDF generation in progress. |
| printing | PDFs generated, sent to print supplier. |
| printed | Letters printed and dispatched to postal carrier. |
| dev | Dev mode order. PDFs available but nothing was mailed. |
Get account
Returns basic account info for the authenticated token. Useful for verifying a key is valid.
MCP Server
LetterAPI ships a native Model Context Protocol server. Any MCP-compatible AI client — Claude Code, Cursor, Windsurf — can send physical letters as a tool call, with no extra code.
Quick start
Setup by client
Available tools
| Tool | Description |
|---|---|
| send_letter | Send one or more physical letters. Accepts |
| get_order | Check the status and PDF links of an order by its token. |
| list_orders | List all recent orders for the account. |
| get_account | Verify the API key and return basic account info (name, email). |
For AI agents. Once configured, your agent can trigger real postal mail with a natural language instruction like "Send an overdue notice to these 3 clients" — no extra code required.
Webhooks
LetterAPI sends webhook events when an order's status changes. Configure your endpoint in the dashboard.
Event payload
Event types
| Event | Triggered when |
|---|---|
| order.printing | PDFs generated, order sent to print supplier. |
| order.printed | Letters printed and handed off to postal carrier. |