How sending direct mail with an API key works
How sending direct mail with an API key works: you create a key, send a request with an address and a design, and Mailr prints the piece, mails it through USPS and reports each step back. Test keys are free and never print, so you can build the whole thing before you pay for anything.
What you need
- An API key. One test key and one live key per account, from the dashboard.
- An address. The person’s name, street, city, two-letter state and ZIP.
- A design. A template id with its merge values, or your own front and back HTML.
- Funds, for live mail only. A prepaid balance you add with a card.
1. Create your API keys
Sign in with your email and open Developers in the dashboard. Create a test key (mlr_test_…) and, when you’re ready, a live key (mlr_live_…). Each account has one of each. The full key is shown once; copy it into your environment as MAILR_API_KEY. If a key leaks, rotate it and the old one stops working at once.
2. Send a test postcard
Send one request with the key in the Authorization header. This one mails a 6x9 thank-you postcard 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 postcard: its id, its status and its events. With a test key nothing prints and nothing is charged, and the piece moves through every status on its own over about eight minutes. Open it in the dashboard to see the front and back rendered with your merge values.
3. Add funds and switch to your live key
Live mail is prepaid. Add funds in Billing with a card, once or every month, and turn on auto top-up if you want the balance to refill itself. Then replace the test key with the live key. The request doesn’t change: the same code now prints and mails, and each piece is taken from your balance when it’s accepted. If the balance doesn’t cover a request, it fails with a 402 and nothing is created.
4. What happens after the request
- Checked. The size, the design, every merge field and the address are checked first. A problem returns a
422that names the field. - Paid. A live piece is paid from your balance in the same step that creates it.
- Proofed. Each design is checked before printing: page size, text outside the safe area, text under 8pt, leftover merge tags, anything where the address goes, and images that are broken or too small.
- Printed. The piece goes into the next print run in Phoenix, in full color on both sides, with the address, return address and postage printed on the back.
- Mailed. The run is handed to USPS.
5. Follow each piece
Every piece has a status: queued, rendered, printed, mailed, then in_transit and processed_for_delivery, or failed with the reason. Read it with GET /v1/postcards/{id} or GET /v1/flats/{id}, or open the Mail tab in the dashboard. Live pieces report through mailed today.
6. Send to many people at once
For a campaign, POST /v1/batches mails one design to up to 1,000 people, each with their own address and merge values. The whole batch is checked and paid for before any piece is created, so it either all goes or none of it does. Send an Idempotency-Key with every request so a retry never mails twice.
7. Order printed items with the same key
Posters, menus, flyers, table cards, rack cards, stickers and yard signs come to you instead of going through the mail. Order them with POST /v1/prints: they’re printed in Phoenix and picked up free or shipped UPS Ground, with shipping priced for the address before you pay. See print.
Questions
Do I need a contract or a sales call?
No. Sign in with your email, create a test key in the dashboard and send your first test postcard. Live mail needs a card and funds in your balance, nothing else.
What does a test piece cost?
Nothing. Test keys never print and never charge. Test pieces move through every status in about eight minutes so you can build against real responses.
What does a live postcard cost?
A 6x9 postcard is $0.89 on pay as you go, with printing, addressing and USPS postage included. A 4x6 is $0.85. The price sheet has every product on every plan.
Can I send to a list instead of one person?
Yes. One request to /v1/batches mails one design to up to 1,000 people, each with their own address and merge values.