Quickstart
- Sign in and create a test key. Test mail is free and never printed.
- Set it as
MAILR_API_KEYin your environment. - Send your first postcard. It shows up in your dashboard right away.
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" }
}'const res = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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" },
}),
});
const postcard = await res.json(); // save postcard.id on your customer recordThe response is the postcard, with an id to save and a status that moves as the piece is printed and mailed:
{
"id": "psc_1f9c2a7e4b10",
"object": "postcard",
"mode": "test",
"status": "queued",
"size": "6x9",
"template": "tmpl_thank_you",
"credits": 2,
"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" },
"description": null,
"events": [
{ "type": "postcard.queued", "status": "queued", "at": "2026-11-18T19:08:00.000Z", "note": "Request accepted" }
],
"created_at": "2026-11-18T19:08:00.000Z",
"url": "https://mailr.dev/app/mail/psc_1f9c2a7e4b10"
}Authentication
Every request sends an API key in the Authorization header: Bearer mlr_test_… or Bearer mlr_live_…. Create and revoke keys in the dashboard. The full key is shown once, when you create it; Mailr keeps only a hash. Read it from an environment variable and never put it in client-side code.
Test and live
The key decides the mode. A test key makes free pieces that are never printed; they move through every status on their own so you can build and test the whole flow. A live key prints and mails for real and spends credits. Live keys unlock once your account has credits.
To test a failure, use an address whose line1 or line2 contains the word undeliverable. The test piece fails after 30 seconds.
Create a piece
POST/v1/postcards
POST/v1/flats
Both take the same body. Flats are single sheets (8.5×11 or 8.5×14) or 11×17 folded to 8.5×11, mailed without an envelope.
sizestringrequiredtoaddressrequiredfromaddressrequiredtemplatestringtmpl_thank_you. The template’s kind and size must match the request.front, backstring{{merge}} tags (up to 500 KB each), or an https link to a PDF.mergeobject{{tags}}. See merge fields.descriptionstringSend either template or front and back.
curl https://api.mailr.dev/v1/flats \
-H "Authorization: Bearer $MAILR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"size": "8.5x11",
"front": "<html>…your front.html with {{first_name}}…</html>",
"back": "<html>…your back.html…</html>",
"to": { "name": "Priya Shah", "line1": "88 Juniper Ave", "line2": "Unit 4", "city": "Portland", "state": "OR", "zip": "97205" },
"from": { "name": "Northwind", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004" },
"merge": { "first_name": "Priya" }
}'Addresses
US addresses only. Mailr prints the recipient address, your return address, postage and the USPS barcode itself, so they never go in your design.
namestringrequiredcompanystringline1stringrequiredline2stringcitystringrequiredstatestringrequiredAZ.zipstringrequiredDesigns
Templates are ready to send: pass the template id and its merge fields. Each template also has print-ready HTML files and a spec (template.json) with the trim size, bleed, safe area and the keep-clear zone where Mailr prints the address block.
To use your own design, start from a template’s front.html and back.html, change them, and send them as front and back. Keep the page size, the 0.125 in bleed and safe area, and leave the keep-clear zone empty. Fonts and images must load from public https links (Google Fonts works).
Merge fields
Every {{tag}} in a design is replaced with the matching value from merge, as plain text. Templates need every one of their fields; a missing field fails with a 422 before anything is made. Values have length limits so they fit the design:
first_name 14promo_code 12last_product 22company 24founder_name 16plan 12update_url 28product_name 22cart_url 28review_url 28Other fields can be up to 200 characters.
Sizes and credits
Test mail is free. Live mail spends credits from your account, and a request fails with a 402 if the balance doesn’t cover it.
| Endpoint | Size (inches) | Credits |
|---|---|---|
/v1/postcards | 4x6 4×6 | 1 |
/v1/postcards | 5.5x8.5 5.5×8.5 | 2 |
/v1/postcards | 6x9 6×9 | 2 |
/v1/postcards | 6x11 6×11 | 2 |
/v1/flats | 8.5x11 8.5×11 | 3 |
/v1/flats | 8.5x14 8.5×14 | 3 |
/v1/flats | 11x17 11×17 | 3 |
Retrieve and list
GET/v1/postcards/{id}
GET/v1/postcards?limit=25
The same works for /v1/flats. Retrieving returns the full piece with its events. Listing returns { "object": "list", "data": [...] }, newest first, up to 100 per request, for the mode of the key you call with. Check a piece’s status by retrieving it; webhooks aren’t available yet.
curl https://api.mailr.dev/v1/postcards/psc_1f9c2a7e4b10 \ -H "Authorization: Bearer $MAILR_API_KEY" curl "https://api.mailr.dev/v1/postcards?limit=25" \ -H "Authorization: Bearer $MAILR_API_KEY"
Statuses
A piece moves through these statuses. Each step is added to events with a time. Test pieces reach each step on a timer:
| Status | Means | Test pieces |
|---|---|---|
queued | Queued | right away |
rendered | Proof ready | after 30 seconds |
printed | Printed | after 2 minutes |
mailed | Mailed | after 4 minutes |
in_ | In transit | after 6 minutes |
processed_ | Out for delivery | after 8 minutes |
failed | Failed | after 30 seconds, for an undeliverable address |
Errors
Errors come back as JSON with a code, a readable message and, for bad input, the field to fix.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_json | The body isn’t a JSON object. |
| 401 | unauthorized | The key is missing, wrong or revoked. |
| 402 | insufficient_credits | A live piece costs more credits than the account has. |
| 404 | not_found | No piece with that id on your account. |
| 422 | invalid_request | A field is missing or out of range; field says which. |
{
"error": {
"code": "invalid_request",
"message": "tmpl_thank_you needs merge.promo_code.",
"field": "merge.promo_code"
}
}