Direct mail for growth teams, with an API underneath. Read the docs →

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

  1. Checked. The size, the design, every merge field and the address are checked first. A problem returns a 422 that names the field.
  2. Paid. A live piece is paid from your balance in the same step that creates it.
  3. 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.
  4. 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.
  5. 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.

START

Send your first test postcard

Sign in, create a test key and run one request. Nothing prints and nothing is charged.

  • Postcards, flats and folded mailers
  • A proof before anything prints
  • Free test mode: nothing prints, nothing charges
  • A status for every piece

Download the template kit?

mailr-kit.zip · about 310 KB · 65 text files

Only HTML, JSON and Markdown files. No programs, scripts or macros, nothing that installs or runs.