Direct mail API: send a postcard with one request
Mailr’s direct mail API is a print and mail API for developers: it prints and mails a postcard or flat from one HTTPS request. Send an address, a template or your own HTML, and the merge fields; you get back the piece with its status. Test keys are free and never print.
Send your first postcard
Create a test key in the dashboard, set it as MAILR_API_KEY, and run one of these. Each sends a 6x9 thank-you postcard built from the tmpl_thank_you template.
curl https://api.mailr.dev/v1/postcards \
-H "Authorization: Bearer $MAILR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"size": "6x9",
"template": "tmpl_thank_you",
"to": { "name": "Ada Park", "line1": "2140 Sample Ave", "city": "Phoenix", "state": "AZ", "zip": "85016" },
"from": { "name": "Acme Outdoor", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004" },
"merge": { "first_name": "Ada", "promo_code": "TRAIL15" }
}'The response is the piece itself. Save its id on your own record so the same person is never mailed twice for the same event.
{
"id": "psc_43eea7ae1aeb",
"object": "postcard",
"mode": "test",
"status": "queued",
"size": "6x9",
"template": "tmpl_thank_you",
"to": { "name": "Ada Park", "line1": "2140 Sample Ave", "city": "Phoenix", "state": "AZ", "zip": "85016" },
"merge": { "first_name": "Ada", "promo_code": "TRAIL15" },
"events": [{ "type": "postcard.queued", "status": "queued", "note": "Request accepted" }],
"url": "https://mailr.dev/app/mail/psc_43eea7ae1aeb"
}Postcard API, flats and what you can send
| Endpoint | Sizes (inches) | Notes |
|---|---|---|
POST /v1/postcards | 4x6, 5.5x8.5, 6x9, 6x11 | Full color both sides, 100 lb silk cover |
POST /v1/flats | 8.5x11, 8.5x14, 11x17 folded | Mailed without an envelope |
GET /v1/postcards/{id} | — | Status and every event so far |
Design each piece with a template and merge fields, or send your own HTML as front and back. Batch orders cost $0.99 for a 6x11 and $0.89 for a 6x9 with postage included; see pricing.
Test mode
A test key (mlr_test_…) creates pieces that never print and cost nothing. They move through the statuses on their own over about eight minutes, so you can build your status handling against real responses. Put “undeliverable” in line1 to see a piece fail. A live key (mlr_live_…) prints and mails.
Statuses
| Status | What it means |
|---|---|
queued | Request accepted |
rendered | Proof rendered from your design |
printed | Off the press |
mailed | Handed to USPS |
in_transit | Moving through USPS |
processed_for_delivery | Out with the local carrier |
failed | Stopped, with the reason in the event note |
Read the current status and the full event list with GET /v1/postcards/{id} or GET /v1/flats/{id}.
Not available yet
- Webhooks. Check status with a GET request for now.
- Letters in envelopes. Flats cover most letter-style mail.
- USPS address verification. The API rejects incomplete or malformed addresses; it doesn’t correct them against USPS records.
- Mail outside the US.
Questions
What’s the best direct mail API for developers?
Lob and PostGrid are the long-established names. Mailr is built for developers and their coding agents: send mail via API with one request, free test keys, templates that ship with print-ready design files and a prompt, and per-piece prices published on the pricing page. Pick the one whose formats, prices and docs fit your app. We compare them in detail on the Lob alternative and PostGrid alternative pages.
Is there a free direct mail API?
Mailr's test mode is free. A test key creates real API objects that move through every status, but nothing prints and nothing is charged, so you can build and test the whole integration first.
Can I send a single postcard through the API?
Yes. One request is one postcard, so you can send a card when a single event happens, like a first order or a failed payment. Live sending is turned on per account during early access.
Is this a physical mail API I can call from any backend?
Yes. It’s plain HTTPS and JSON, so any language that can make a POST request can send physical mail: Python, Node.js, Ruby, Go, PHP, or a no-code tool like Zapier.
Postcard API or letter API: what does Mailr send?
Postcards in four sizes and flats: single 8.5x11 or 8.5x14 sheets, or an 11x17 sheet folded to 8.5x11, mailed without an envelope. Letters folded into envelopes aren't available.
Does it work with AI coding agents?
Yes. Every template ships with print-ready design files, a spec an agent can read, and a prompt you paste into Claude Code, Cursor or Codex. The whole API is summarized for agents at mailr.dev/llms.txt.