Direct mail API for Zapier
Direct mail API for Zapier: add a Webhooks by Zapier step after any trigger, such as a paid Shopify order or a new Google Sheets row, and it sends the address to Mailr with your key in the headers. Mailr prints the postcard or letter, mails it and returns an id you can write back.
What to mail from Zapier
| When this happens | Mail this |
|---|---|
| Shopify: New Paid Order | A thank-you postcard with a code for the next order. (First-order thank you) |
| Google Sheets: New Spreadsheet Row | A review request card for each row your team adds. (Review request) |
| Webhooks by Zapier: Catch Hook, called by your app at signup | A founder welcome letter, mailed flat (Custom Request to /v1/flats). (Welcome letter) |
Set it up
- Check your plan. Webhooks by Zapier is part of the Professional, Team and Enterprise plans. It isn't on the Free plan.
- Save your return address in Mailr. In the Mailr dashboard, open Settings and save your return address. The step can then leave out from, which keeps it to the recipient's fields.
- Add the action. After your trigger, add Webhooks by Zapier with the event POST. Set the URL to https://api.mailr.dev/v1/postcards, Payload Type to json and Unflatten to yes.
- Map the data. Add the Data rows from the first tab and map your trigger's fields into them. Keys with double underscores, like to__line1, become the nested to and merge objects Mailr needs, and Zapier escapes each value for you.
- Add the headers. Add Authorization with the value Bearer mlr_test_... and Idempotency-Key with a value built from the trigger's record id, such as shopify-thank-you- followed by the order ID.
- Test, write back, go live. Test the step. With a test key the postcard appears in your Mailr dashboard and never prints. Map the returned id into a later step, such as Update Spreadsheet Row, then change the header to your mlr_live_ key.
The Webhooks by Zapier step
App and event Webhooks by Zapier > POST
URL https://api.mailr.dev/v1/postcards
Payload Type json
Unflatten yes
Data
size 6x9
template tmpl_thank_you
to__name {{shipping name}}
to__line1 {{shipping address 1}}
to__line2 {{shipping address 2}} (an empty value is ignored)
to__city {{shipping city}}
to__state {{shipping province code}} (two letters, like AZ)
to__zip {{shipping zip}}
merge__first_name {{shipping first name}} (14 characters at most)
merge__promo_code THANKS15
Headers
Authorization Bearer mlr_test_...
Idempotency-Key shopify-thank-you-{{order ID}}
No from fields: Mailr prints the return address saved in Settings.
The response's id is the postcard id. Map it into a later step to keep it.- Custom Request sends the Data box exactly as typed. A mapped value with a double quote in it, like a company called The "Best" Shop, breaks the JSON and Mailr answers 400 invalid_json. The POST action builds the JSON for you, so use it unless you need a body it can't express.
- Autoreplay, on the Professional plan and up, retries an errored step up to five times over about ten and a half hours. The Idempotency-Key makes each replay return the first piece instead of mailing again, since Mailr keeps the key for 24 hours.
- Mailr needs a two-letter state and caps merge values (first_name 14 characters, company 24). Add a Formatter by Zapier step to shorten values, or the step errors with Mailr's 422 message naming the field.
- Zapier pauses a Zap whose runs error 95% or more of the time, so fix address problems at the source rather than letting the step fail.
What it costs
Each live piece is paid from your Mailr balance, printing and postage included: a 4x6 postcard is $0.85, a 6x9 $0.89 and an 8.5x11 letter $0.95 on pay as you go, less on a plan. Test pieces are free. All prices.
Templates that fit: First-order thank you (6x9), Review request (4x6), Welcome letter (8.5x11).
Questions
Is there a Mailr app in Zapier?
No. Mailr has no Zapier app yet, so the step uses Webhooks by Zapier to call the REST API directly. It works with any trigger in any Zap.
Can I mail a whole list at once from Zapier?
A Zap runs once per trigger record, so each run sends one piece. To send a list as a single request, POST it to /v1/batches (up to 1,000 recipients) from Make, n8n or your own code.
How do I find out when a postcard is delivered?
Mailr has no webhooks yet, so it can't start a Zap when a status changes. A Webhooks by Zapier GET step to /v1/postcards/{id}, with the same Authorization header, returns the status and every event.
What does each run cost on the Mailr side?
One live piece at one price, printing and postage included: $0.89 for a 6x9 postcard on pay as you go, less on a plan. Pieces made with a test key are free. Zapier bills its tasks separately.