How to send postcards programmatically
To send postcards programmatically from your app, POST an address, a design and the merge fields to https://api.mailr.dev/v1/postcards. Mailr prints it, addresses it and hands it to USPS. Below: working Python, Node.js and cURL code, checking the status, and sending your own design.
1. Get a test key
Sign in at mailr.dev/login (the sign-in link creates your account) and create a test key in the dashboard. Test keys start with mlr_test_. Pieces made with them move through every status but never print and never cost anything.
Keep the key in an environment variable, not in your code: export MAILR_API_KEY=mlr_test_…
2. Send a postcard with Python, Node.js or cURL
This sends a 6x9 thank-you card from the tmpl_thank_you template with two merge fields. Python uses the requests library; Node.js 18 and later has fetch built in.
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" }
}'A 201 response returns the postcard with an id like psc_43eea7ae1aeb and the status queued. Store that id on the customer’s record. It’s how you avoid mailing the same person twice for the same event.
3. Check where it is
Fetch the postcard by id to see its current status and every event so far. With a test key the status moves from queued to processed_for_delivery in about eight minutes, which is handy for testing a status page.
curl https://api.mailr.dev/v1/postcards/$POSTCARD_ID \
-H "Authorization: Bearer $MAILR_API_KEY"4. Send your own design
Instead of a template, send HTML for each side as front and back. Size each page to the card plus 0.125 inch of bleed (11.25 × 6.25 inches for a 6x11) and keep the back’s lower-right 4 × 2.375 inch block empty: that’s where Mailr prints the address, postage and barcode. Merge tags like {{first_name}} work in your HTML too.
curl https://api.mailr.dev/v1/postcards \
-H "Authorization: Bearer $MAILR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"size": "6x11",
"front": "<html><body style=\"margin:0;width:11.25in;height:6.25in;background:#151517;color:#fff;font:700 48px sans-serif\"><p style=\"padding:1in\">Hi {{first_name}}</p></body></html>",
"back": "<html><body style=\"margin:0;width:11.25in;height:6.25in;font:24px sans-serif\"><p style=\"padding:.5in;width:5in\">Thanks for being here.</p></body></html>",
"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" }
}'The free 6x11 template marks every boundary if you’d rather design in a tool first.
5. Handle errors
| Status | Code | Fix |
|---|---|---|
| 401 | unauthorized | The Authorization: Bearer header is missing or the key was revoked. |
| 402 | insufficient_credits | A live key ran out of credits. |
| 422 | invalid_request | Read error.field: a missing merge field, a bad ZIP, or a size the template wasn’t designed for. |
Questions developers ask
How do I send a physical postcard from my app?
Call one API from your backend when the event happens, like a signup or a first order: POST /v1/postcards with the customer’s address, a design and the merge fields. Mailr prints, addresses and mails it. That’s steps 1 and 2 above.
Can I send a postcard with Python?
Yes. The Python tab in step 2 is a complete script using requests. Set MAILR_API_KEY and run it.
How do I send a postcard with Node.js?
Node 18 and later have fetch built in, so the Node.js tab needs no packages. Save it as send.mjs and run node send.mjs.
Is there an API to send a letter in the mail?
Mailr sends letter-style mail as a flat: a single 8.5x11 sheet mailed without an envelope, created with POST /v1/flats. The welcome letter template is one. Letters folded into envelopes aren’t available.
How do I send letters or postcards programmatically in bulk?
Loop over your list and make one request per address, saving each returned id. For a one-off batch from a spreadsheet, our print and mail service takes the file instead.
6. Go live
Swap the test key for a live one (mlr_live_…) and the same code prints and mails. During early access we turn on live sending account by account; ask from the API page.