Get API key

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 https://api.letterapi.io. No versioning prefix required.

Quick start

javascriptCopy
// 1. Install (optional SDK — or use fetch directly)
// npm install letterapi
 
// 2. Send your first letter
const response = await fetch('https://api.letterapi.io/sendMail', {
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
templateToken: 'YOUR_TEMPLATE_TOKEN',
fields: { name: 'Marie', amount: '$1,200' },
addresses: {
addr_1: 'Marie Tremblay, 123 Rue Saint-Denis, Montréal QC H2X 1Z6',
},
}),
});
 
const data = await response.json();
// { orderId: 142, token: "8f92kx3m", isDev: false, creditAfter: 9452 }

Authentication

All requests must include your API key in the Authorization header. No Bearer prefix — just the raw token.

http
Authorization: ltr_live_xxxxxxxxxxxxxxxxxx
Key typePrefixBehavior
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.

BehaviorLiveDev
PDFs generated✓✓
Letters mailed✓✗
Billing applied✓✗
Max addresses per callUnlimited3
Order statusprintingdev

Errors

All errors return a JSON object with an error key describing what went wrong.

json
{ "error": "templateToken, fields and addresses are required" }
StatusMeaning
201Order created successfully.
400Missing or invalid parameters. Check templateToken, fields, and addresses.
401Missing or invalid API key.
404Template not found, or your account doesn't have access to it.
500Internal server error. Contact support if this persists.

Send mail

Create an order and trigger letter generation. Each address in the addresses object produces one physical letter.

POST https://api.letterapi.io/sendMail

Request body

ParameterTypeRequiredDescription
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

javascriptCopy
await fetch('https://api.letterapi.io/sendMail', {
method: 'POST',
headers: {
'Authorization': 'ltr_live_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
templateToken: 'a3f2b1c8',
fields: {
clientName: 'Marie Tremblay',
invoiceNumber: '#4821',
amount: '$1,200.00',
},
addresses: {
addr_1: 'Marie Tremblay, 123 Rue Saint-Denis, Montréal QC H2X 1Z6',
addr_2: 'Jean Gagné, 45 Boul. René-Lévesque, Québec QC G1R 2B5',
},
}),
});

Response

201Order created
json
{
"message": "Order created with 2 PDF(s)",
"orderId": 142,
"token": "8f92kx3m",
"isDev": false,
"creditAfter": 9452 // remaining credit in cents, omitted if no pricing configured
}

Example — Python

pythonCopy
import requests
 
response = requests.post(
"https://api.letterapi.io/sendMail",
headers={
"Authorization": "ltr_live_xxxxxxxxx",
"Content-Type": "application/json",
},
json={
"templateToken": "a3f2b1c8",
"fields": { "clientName": "Marie Tremblay", "amount": "$1,200" },
"addresses": {
"a1": "Marie Tremblay, 123 Rue Saint-Denis, Montréal QC H2X 1Z6"
},
},
)
print(response.json())

Example — PHP

phpCopy
$payload = [
'templateToken' => 'a3f2b1c8',
'fields' => ['clientName' => 'Marie Tremblay', 'amount' => '$1,200'],
'addresses' => ['a1' => 'Marie Tremblay, 123 Rue Saint-Denis, Montréal QC'],
];
 
$ch = curl_init('https://api.letterapi.io/sendMail');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: ltr_live_xxxxxxxxx',
'Content-Type: application/json',
],
]);
$result = json_decode(curl_exec($ch), true);

List orders

Returns all orders for the authenticated account, sorted by most recent first.

GET https://api.letterapi.io/orders

Query parameters

ParameterTypeRequiredDescription
token string optional Filter to a specific order by its token. Returns 404 if not found.

Response

json
{
"ok": true,
"orders": [
{
"id": 142,
"token": "8f92kx3m",
"templateToken": "a3f2b1c8",
"status": "printing", // pending | printing | printed | Dev
"unit": 2, // number of letters in this order
"unitPrice": 349, // price per letter in cents
"total": 698, // total cost in cents
"pdfs": [
"https://api.letterapi.io/mailingReport/8f92kx3m/addr_1.pdf",
"https://api.letterapi.io/mailingReport/8f92kx3m/addr_2.pdf"
],
"createdAt": "2026-04-10T18:42:00.000Z"
}
]
}

Get order

Retrieve a single order by token. Useful for checking status and accessing generated PDFs.

GET https://api.letterapi.io/orders?token={token}
ⓘ

This is the same /orders endpoint with a token query param. Returns 404 if the token doesn't exist or belongs to another account.

Order statuses

StatusMeaning
pendingOrder received, PDF generation in progress.
printingPDFs generated, sent to print supplier.
printedLetters printed and dispatched to postal carrier.
devDev 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.

GET https://api.letterapi.io/me
json
{
"ok": true,
"account": {
"id": 12,
"name": "Acme Corp",
"email": "dev@acme.com"
}
}

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

bashCopy
npx @letterapi/mcp --key ltr_live_xxxxxxxxx

Setup by client

Claude Code Claude Desktop Cursor Windsurf ChatGPT
bash
# Run once — Claude Code detects it automatically
claude mcp add letterapi -- npx @letterapi/mcp --key ltr_live_xxxxxxxxx

Available tools

ToolDescription
send_letterSend one or more physical letters. Accepts templateToken, fields, and addresses.
get_orderCheck the status and PDF links of an order by its token.
list_ordersList all recent orders for the account.
get_accountVerify 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

json
{
"event": "order.printed",
"orderId": 142,
"token": "8f92kx3m",
"status": "printed",
"timestamp": "2026-04-10T22:15:00.000Z"
}

Event types

EventTriggered when
order.printingPDFs generated, order sent to print supplier.
order.printedLetters printed and handed off to postal carrier.