HubSpot direct mail: send a letter from a workflow
HubSpot direct mail with Mailr runs from a workflow's custom code action: when a contact's deal closes, a few lines of Node.js send their address to Mailr, which prints a welcome letter, mails it with USPS and returns an id you save on the contact.
What to mail from HubSpot
| When this happens | Mail this |
|---|---|
| A contact's associated deal moves to Closed won | A founder welcome letter, mailed flat. (Welcome letter) |
| Lifecycle stage becomes Customer, then a 30-day delay | A review request card. (Review request) |
| A contact joins your lapsed-customers list (list membership trigger) | A win-back card with a code and the product they last bought. (Win-back) |
Set it up
- Check your plan. Custom code actions need Data Hub Professional or Enterprise (formerly Operations Hub). On other plans, trigger a Zapier, Make or n8n step instead (see the guide linked below).
- Create the workflow. Make a contact-based workflow. For the trigger, filter on the associated deal: Deal stage is Closed won. Leave re-enrollment off so each contact gets one letter.
- Add a custom code action. Choose Node.js 24. Add a secret named MAILR_API_KEY with your Mailr test key. Under properties to include in code, add First name (firstname), Last name (lastname), Company name (company), Street address (address), City (city), State/Region (state) and Postal code (zip).
- Paste the code and define outputs. Paste the code below, then add two data outputs, mailr_id and mailr_error, both strings. Test the action on a contact with a US address; with a test key nothing prints.
- Save the id, then go live. Add an Edit record action that copies mailr_id into a custom contact property such as Mailr letter id. When it works, change the secret's value to your mlr_live_ key.
The custom code action
// Secret: MAILR_API_KEY. Properties: firstname, lastname, company, address, city, state, zip
const axios = require("axios");
exports.main = async (event, callback) => {
const p = event.inputFields;
const state = (p.state || "").trim().toUpperCase();
if (!/^[A-Z]{2}$/.test(state)) {
// Mailr needs a two-letter code, and HubSpot's State/Region can hold anything.
return callback({ outputFields: { mailr_id: "", mailr_error: `State "${p.state}" is not a two-letter code` } });
}
try {
const { data } = await axios.post(
"https://api.mailr.dev/v1/flats",
{
size: "8.5x11",
template: "tmpl_welcome",
to: {
name: `${p.firstname || ""} ${p.lastname || ""}`.trim().slice(0, 40),
line1: p.address,
city: p.city,
state,
zip: p.zip,
},
from: { name: "Northwind", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
merge: {
first_name: (p.firstname || "").slice(0, 14),
company: (p.company || "your team").slice(0, 24),
founder_name: "Sam",
},
},
{
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Idempotency-Key": `hubspot-welcome-${event.object.objectId}`,
},
timeout: 15000, // the whole action has 20 seconds
},
);
callback({ outputFields: { mailr_id: data.id, mailr_error: "" } });
} catch (err) {
const status = err.response?.status;
// HubSpot retries 429 and 5xx errors from axios for up to three days; the Idempotency-Key makes that safe.
if (!status || status === 429 || status >= 500) throw err;
callback({ outputFields: { mailr_id: "", mailr_error: err.response.data?.error?.message || `HTTP ${status}` } });
}
};- The Send a webhook action can't build Mailr's request: its body is made of key and value pairs, and Mailr needs nested to, from and merge objects. Custom code builds the body exactly.
- Custom code must finish within 20 seconds with 128 MB of memory. The 15-second axios timeout keeps the call inside that.
- Secrets are read with process.env. All of an action's secret values together can be at most 1,000 characters, and HubSpot keeps them out of the code.
- HubSpot's State/Region property takes whatever a form or import puts in it, and Mailr needs a two-letter code. Use a two-letter dropdown on your forms, or the code returns mailr_error for that contact.
- HubSpot set November 17, 2026 as the date to move Node.js 16 and 20 actions to Node.js 24, and new actions can't use Node.js 20. Write new ones on 24.
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: Welcome letter (8.5x11), Review request (4x6), Win-back (6x11).
Questions
Is there a Mailr app in the HubSpot marketplace?
No. Mailr has no HubSpot app and no webhooks of its own yet. The workflow calls Mailr's REST API from a custom code action, and you can check a letter's status later with GET /v1/flats/{id}.
Can I do this without Data Hub Professional?
Not inside HubSpot: both custom code and webhook actions need it. Use a Zapier, Make or n8n step that your HubSpot trigger starts, or poll HubSpot's API from your own app and call Mailr there.
Why a letter instead of a postcard?
A new customer reads a founder's note, and the welcome template is a letter-style 8.5x11 flat that mails without an envelope for $0.95 on pay as you go. Postcards work the same way: change the endpoint to /v1/postcards and send a postcard size and template.
Will a contact get two letters if they're enrolled again?
Not within 24 hours: the Idempotency-Key returns the first letter. After that, leave re-enrollment off, or add an enrollment filter that skips contacts whose Mailr letter id is known.