Direct mail API for Workiz
Direct mail API for Workiz: create a webhook rule in Workiz's Developer settings that fires when a job's status changes to Done, and your receiver sends the client's address from the payload to Mailr, which prints the card, pays the postage and mails it.
What to mail from Workiz
| When this happens | Mail this |
|---|---|
| Webhook rule: Job status → Done | A review card a few days later, naming the job type, with a short link to your review page. (Review request) |
| Webhook rule: Job status → Done, with a condition on an install job type | An 8.5x11 letter with the install date and the date to register the equipment with the manufacturer. |
| Estimates still Pending 7 days after they were sent (GET /v2/estimates, sentDate) | A 6x9 follow-up card with the estimate number and the number to book. |
| Each spring and fall: Done maintenance jobs from 11 to 13 months ago (GET /v2/jobs) | A 6x9 tune-up reminder, sent as batches of up to 1,000. |
| A tech hands out leave-behinds at the door (your own reorder, not a Workiz event) | Not mailed: 4.25x11 rack cards ordered with POST /v1/prints. |
Set it up
- Turn on the Developer API. Enable the Developer API add-on from Workiz's Feature center. Then open the profile icon > Settings > Integrations > Developer; the v2 tab has your credentials, sent as Authorization: Bearer to https://api.workiz.com/crm/api. If the Developer page is missing, an admin has to give you the Account Settings permission.
- Create the webhook rule. On the v2 tab, select Create new > Webhook. Give the rule a title, set the trigger to the job status changing to Done, select add url and enter your receiver's URL and an auth key (a long random string). Add a condition if you only want some job types, then select Add automation.
- Check the auth key. Workiz sends the auth key as Authorization: Bearer <auth key>. It's the only check Workiz offers, so reject any request without it.
- Map the payload. The payload's data is the full job, the same as GET /v2/jobs/{id}. The address is in data.clientInfo.addressDetails (address, unit, city, state, zipCode) and the name in clientInfo.firstName and lastName. Workiz's own example shows state as Ohio, so convert full names to two-letter codes.
- Send it to Mailr. POST to /v1/postcards with an Idempotency-Key built from data.id and save the postcard id. Turning a job back to Done and again won't print a second card within 24 hours.
- Watch the logs, then go live. Workiz's Developer page has View Logs; filter by Webhook and Errors only to see failed deliveries. Test with your mlr_test_ key (nothing prints), then switch to your mlr_live_ key.
Code: the webhook receiver and estimate follow-ups
// npm i express. Env: WORKIZ_AUTH_KEY (the rule's auth key), MAILR_API_KEY
import crypto from "node:crypto";
import express from "express";
const app = express();
const STATES = "AL Alabama|AK Alaska|AZ Arizona|AR Arkansas|CA California|CO Colorado|CT Connecticut|DE Delaware|DC District of Columbia|FL Florida|GA Georgia|HI Hawaii|ID Idaho|IL Illinois|IN Indiana|IA Iowa|KS Kansas|KY Kentucky|LA Louisiana|ME Maine|MD Maryland|MA Massachusetts|MI Michigan|MN Minnesota|MS Mississippi|MO Missouri|MT Montana|NE Nebraska|NV Nevada|NH New Hampshire|NJ New Jersey|NM New Mexico|NY New York|NC North Carolina|ND North Dakota|OH Ohio|OK Oklahoma|OR Oregon|PA Pennsylvania|RI Rhode Island|SC South Carolina|SD South Dakota|TN Tennessee|TX Texas|UT Utah|VT Vermont|VA Virginia|WA Washington|WV West Virginia|WI Wisconsin|WY Wyoming";
const BY_NAME = Object.fromEntries(STATES.split("|").map((s) => [s.slice(3).toLowerCase(), s.slice(0, 2)]));
const usState = (v = "") => (/^[a-z]{2}$/i.test(v.trim()) ? v.trim().toUpperCase() : BY_NAME[v.trim().toLowerCase()]);
app.post("/workiz/webhooks", express.json(), (req, res) => {
const sent = req.get("Authorization") || "";
const want = `Bearer ${process.env.WORKIZ_AUTH_KEY}`;
if (sent.length !== want.length || !crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(want))) return res.sendStatus(401);
res.sendStatus(200);
const job = req.body.data;
if (job?.status !== "Done") return;
reviewCard(job).catch((err) => console.error(job.id, err.message));
});
async function reviewCard(job) {
const c = job.clientInfo;
const a = c?.addressDetails;
const state = usState(a?.state);
const zip = a?.zipCode ?? a?.zipcode; // the API reference says zipCode, the help article's example zipcode
if (!a?.address || !state || !zip || !c.firstName) return console.warn(`Job ${job.serialId}: no name or address`);
const res = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `workiz-review-${job.id}`,
},
body: JSON.stringify({
size: "4x6",
template: "tmpl_review_request",
to: {
name: `${c.firstName} ${c.lastName || ""}`.trim().slice(0, 40),
line1: a.address, line2: a.unit || undefined, city: a.city, state, zip,
},
from: { name: "Example Garage Doors", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
merge: {
first_name: c.firstName.split(" ")[0].slice(0, 14),
product_name: (job.jobType?.name || "service visit").slice(0, 22),
review_url: "example.com/review",
},
description: `Review card, Workiz job ${job.serialId}`,
}),
});
const piece = await res.json();
if (!res.ok) throw new Error(`Mailr ${res.status}: ${piece.error.message}`);
await saveMailrId(job.id, piece.id);
}
app.listen(3000);- Workiz webhooks only work with job, lead, estimate and invoice triggers. A rule made in the Automation Center with the post webhook action also shows in the Webhooks tab.
- The payload has trigger (type and timestamp), data (the full record, the same as GET /v2/jobs/{id}) and metadata (the rule). Any 2xx answer counts as received.
- Workiz's API reference names the ZIP field zipCode and its help article's example zipcode, and the reference example gives state as a full name. The sample reads both ZIP spellings and converts state names.
- Without date filters, GET /v2/jobs returns the last 30 days by scheduled date. Pass dateProperty, dateOperator and date together, with between taking two dates joined by an underscore.
- Mailr needs a two-letter state and a 5-digit or ZIP+4 code. A malformed one comes back as a 422 naming the field, with nothing charged; add verify: true to check deliverability too.
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).
Questions
Do Workiz webhooks need a paid add-on?
Workiz's help center says the Developer API add-on is enabled from the Feature center before you get API credentials. Webhook rules are created on the same Developer page; check with Workiz which plans include the add-on.
Can Workiz post straight to Mailr without a receiver?
No. Workiz sends its own job payload, and Mailr needs its own body with to, merge and a design. A small receiver, or a Zapier or n8n step, turns one into the other.
Will moving a job back and forth from Done mail twice?
Not within 24 hours: the Idempotency-Key built from the job id returns the first postcard. Save the postcard id with the job so later runs skip it too.
What does a tune-up reminder mailing cost?
A 6x9 postcard is $0.89 on pay as you go, printing and postage included, and less on a plan. Send up to 1,000 recipients per batch request.
Can I mail the neighbors of a finished job?
Only from a list you own or buy. Mailr mails the addresses you send and doesn't sell lists or look up neighbors.