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

Direct mail API for n8n

Direct mail API for n8n: an HTTP Request node with a Header Auth credential posts the address to Mailr whenever a workflow runs, with merge fields filled in by expressions, and a Schedule Trigger can mail a whole list each night as one batch.

What to mail from n8n

When this happensMail this
Google Sheets Trigger: Row addedA review request card for each row your team adds. (Review request)
Typeform Trigger: a signup form response is submittedA founder welcome letter, mailed flat (URL /v1/flats). (Welcome letter)
Schedule Trigger: every day at 2:00Win-back postcards to everyone on your lapsed list, one batch per 1,000. (Win-back)

Set it up

  1. Create the credential. In Credentials, add a Header Auth credential named Mailr, with Name set to Authorization and Value set to Bearer followed by your mlr_test_ key. Keeping the key in a credential, not in a header field, keeps it out of the workflow you share or export.
  2. Add the HTTP Request node. Method POST, URL https://api.mailr.dev/v1/postcards. Authentication: Generic Credential Type, then Header Auth, then the Mailr credential. Save your return address in Mailr's Settings so the body can leave out from.
  3. Add the Idempotency-Key header. Turn on Send Headers and add Idempotency-Key with an expression built from the item's id, such as sheet-review-{{ $json.id }}. Give your sheet an id column if it doesn't have one.
  4. Send the body. Turn on Send Body, choose Body Content Type JSON and Specify Body Using JSON, then paste the body from the first tab. Text values go through JSON.stringify() so a name with a quote in it can't break the JSON.
  5. Handle errors. In the node's Settings, turn on Retry On Fail, and set On Error to Continue (using error output) so a rejected address goes down a second branch, for example to write Mailr's message back to the row.
  6. Add the nightly batch, then go live. Build the second workflow from the second tab: Schedule Trigger, the node that reads your list, a Code node that groups it into batches, and an HTTP Request to /v1/batches. Save and publish both workflows, test with the test key, then put your mlr_live_ key in the credential's value.

HTTP Request node settings and code

HTTP Request node
  Method            POST
  URL               https://api.mailr.dev/v1/postcards
  Authentication    Generic Credential Type > Header Auth > Mailr
                    (Name: Authorization, Value: Bearer mlr_test_...)
  Send Headers      on   Idempotency-Key = sheet-review-{{ $json.id }}
  Send Body         on   Body Content Type: JSON, Specify Body: Using JSON
  Settings          Retry On Fail: on   On Error: Continue (using error output)

JSON (the item comes from Google Sheets Trigger: Row added)
{
  "size": "4x6",
  "template": "tmpl_review_request",
  "to": {
    "name": {{ JSON.stringify($json.name) }},
    "line1": {{ JSON.stringify($json.street) }},
    "city": {{ JSON.stringify($json.city) }},
    "state": {{ JSON.stringify($json.state) }},
    "zip": {{ JSON.stringify(String($json.zip).padStart(5, "0")) }}
  },
  "merge": {
    "first_name": {{ JSON.stringify(String($json.first_name).slice(0, 14)) }},
    "product_name": {{ JSON.stringify(String($json.product).slice(0, 22)) }},
    "review_url": "acme.co/review"
  }
}
  • Expressions in a Using JSON body are filled in as text before the JSON is read, so wrap text values in JSON.stringify(). A name like Mike "Mac" Ortiz would otherwise break the body and Mailr would answer 400 invalid_json.
  • Retry On Fail reruns the node on any error, a 422 included. The Idempotency-Key makes each retry return the first piece instead of mailing again, for 24 hours.
  • Google Sheets can turn a ZIP like 02134 into the number 2134. The examples pad it back to five digits; formatting the column as plain text avoids it.
  • The Schedule Trigger uses the workflow's time zone, or the instance's if the workflow has none. The workflow only runs on schedule once it's saved and published.
  • A batch is all or nothing and holds up to 1,000 recipients. If one address is invalid, Mailr answers 422 with a field like recipients[3].to.state, and nothing is created.

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: Review request (4x6), Welcome letter (8.5x11), Win-back (6x11).

Questions

Is there a Mailr node for n8n?

No. Mailr has no n8n node yet, so workflows use the HTTP Request node with a Header Auth credential to call the REST API directly.

Does this work on n8n Cloud and self-hosted n8n?

Yes. HTTP Request, Code and Schedule Trigger are core nodes in both, and nothing here needs a community node or an environment variable.

How do I check whether a postcard was delivered?

Mailr has no webhooks yet, so it can't start a workflow. An HTTP Request node with GET https://api.mailr.dev/v1/postcards/{id} and the same credential returns the status and every event; run it on a schedule if you want statuses in your sheet.

What does a nightly batch cost?

Each card is one piece at one price, printing and postage included: a 6x11 win-back card is $0.99 on pay as you go, less on a plan. Pieces made with a test key are free and never print.

The code on this page is written against the Mailr API as it works today. Test it with your test key first; nothing prints until you use a live key.
N8N

Mail from n8n today

Get a free test key, send one postcard to yourself and watch it move through every status.

  • 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.