Direct mail API for Jobber
Direct mail API for Jobber: subscribe your Jobber app to job and quote webhooks, look up the client and property address in Jobber's GraphQL API, and send it to Mailr, which prints the card, pays the postage and mails it.
What to mail from Jobber
| When this happens | Mail this |
|---|---|
| JOB_CLOSED | A review card a few days later, naming the work, with a short link to your review page. (Review request) |
| QUOTE_SENT, with no QUOTE_APPROVED for the same quote 7 days later | A 6x9 follow-up card with the quote number and the number to call. |
| CLIENT_CREATE | An 8.5x11 welcome letter with the service area, the after-hours line and what the first visit includes. |
| JOB_CLOSED on an install job (a new water heater, furnace or AC system) | An 8.5x11 letter with the install date and the date to register the equipment with the manufacturer. |
| Each spring: clients whose jobs closed 11 to 13 months ago (from your own record of JOB_CLOSED events) | A 6x9 seasonal reminder, sent as batches of up to 1,000. |
Set it up
- Create the app. In Jobber's Developer Center, create an app with read scopes for clients, jobs and quotes; each webhook topic needs the read scope for its object. Jobber says custom integrations are for approved Jobber customers and developers, and an app left in Draft can connect to up to 5 paying Jobber accounts without an app review.
- Add the webhooks. On the app's settings page, add one webhook per topic, each with your HTTPS URL: JOB_CLOSED, QUOTE_SENT and QUOTE_APPROVED. Pick them from the topic list there; Jobber lists every topic in the Developer Center and in WebHookTopicEnum in its GraphQL schema.
- Connect the account. The contractor connects your app through Jobber's OAuth 2.0 flow. Store the account's access and refresh tokens against its accountId, which every webhook carries.
- Verify and answer within 1 second. Check the X-Jobber-Hmac-SHA256 header: a base64 HMAC-SHA256 of the raw body, keyed with your app's OAuth client secret. Return 200 at once and do the GraphQL lookup and the Mailr call afterwards, from a queue.
- Look up the address and mail. The payload carries only the topic, accountId and itemId. Query the job's client and property address at https://api.getjobber.com/api/graphql, then POST to Mailr with an Idempotency-Key built from the itemId, and save the postcard id with the job.
- Test, then go live. Close a job on a test account with your mlr_test_ key in place and check the postcard in the Mailr dashboard; nothing prints. Then switch to your mlr_live_ key.
Code: the webhook receiver and the nightly quote follow-up
// npm i express. Env: JOBBER_CLIENT_SECRET, MAILR_API_KEY
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/jobber/webhooks", express.raw({ type: "*/*" }), (req, res) => {
const sent = req.get("X-Jobber-Hmac-SHA256") || "";
const ours = crypto.createHmac("sha256", process.env.JOBBER_CLIENT_SECRET).update(req.body).digest("base64");
if (sent.length !== ours.length || !crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(ours))) return res.sendStatus(401);
res.sendStatus(200); // Jobber wants an answer within 1 second; do the work after
const { topic, accountId, itemId } = JSON.parse(req.body).data.webHookEvent;
handle(topic, accountId, itemId).catch((err) => console.error(topic, itemId, err));
});
async function handle(topic, accountId, itemId) {
if (topic === "QUOTE_SENT") return recordQuoteSent(accountId, itemId); // your table; the nightly job reads it
if (topic === "QUOTE_APPROVED") return markQuoteApproved(itemId);
if (topic !== "JOB_CLOSED") return;
const { job } = await jobber(accountId, JOB_QUERY, { id: itemId });
const a = job.property?.address;
const state = (a?.province || "").trim().toUpperCase(); // Mailr needs a two-letter code
if (!a?.street1 || !/^[A-Z]{2}$/.test(state) || !job.client.firstName) {
return console.warn(`Job #${job.jobNumber}: fix the client name or address in Jobber`);
}
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": `jobber-review-${itemId}`, // Jobber can deliver the same event twice
},
body: JSON.stringify({
size: "4x6",
template: "tmpl_review_request",
to: {
name: `${job.client.firstName} ${job.client.lastName}`.trim().slice(0, 40),
line1: a.street1, line2: a.street2 || undefined, city: a.city, state, zip: a.postalCode,
},
from: { name: "Example Plumbing", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
merge: {
first_name: job.client.firstName.slice(0, 14),
product_name: (job.title || "service visit").slice(0, 22),
review_url: "example.com/review",
},
description: `Review card, Jobber job #${job.jobNumber}`,
}),
});
const piece = await res.json();
if (!res.ok) throw new Error(`Mailr ${res.status}: ${piece.error.message}`);
await saveMailrId(itemId, piece.id);
}
const JOB_QUERY = `query Job($id: EncodedId!) {
job(id: $id) {
jobNumber
title
client { firstName lastName }
property { address { street1 street2 city province postalCode } }
}
}`;
async function jobber(accountId, query, variables) {
const res = await fetch("https://api.getjobber.com/api/graphql", {
method: "POST",
headers: {
Authorization: `Bearer ${await tokenFor(accountId)}`, // your stored OAuth token for this account
"X-JOBBER-GRAPHQL-VERSION": "2025-04-16", // an API version Jobber still supports
"Content-Type": "application/json",
},
body: JSON.stringify({ query, variables }),
});
const body = await res.json();
if (body.errors) throw new Error(body.errors[0].message); // errors come back with HTTP 200
return body.data;
}
app.listen(3000);- Jobber's public docs name CLIENT_CREATE, INVOICE_UPDATE and APP_DISCONNECT and say the full list is in the Developer Center and in WebHookTopicEnum. JOB_CLOSED, QUOTE_SENT and QUOTE_APPROVED are values of that enum, not shown on the public page; check them in the topic list when you add each webhook.
- Webhooks must be answered within 1 second. If answers are consistently slow or many fail, Jobber may turn off the app's webhooks, and the Developer Center doesn't alert you when deliveries fail.
- Delivery is at least once, and one action can fire the same topic twice about a second apart (a payment on an invoice sends INVOICE_UPDATE twice). The Idempotency-Key returns the first postcard for 24 hours, and the saved id covers later repeats.
- The payload holds topic, appId, accountId, itemId and occurredAt, not the object. Apps created before December 8, 2023 receive occuredAt, and apps created before April 11, 2022 receive form-encoded payloads.
- Every GraphQL call needs the X-JOBBER-GRAPHQL-VERSION header, and errors come back with HTTP 200 in a top-level errors array, so check for it.
- Jobber's province field holds whatever was typed, and Mailr needs a two-letter state. The samples skip anything else; map full state names to codes first if your clients have them.
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
Does the Jobber webhook include the client's address?
No. It carries the topic, the account id and the id of the job, quote or client that changed. Your receiver queries Jobber's GraphQL API for the name and address, then calls Mailr.
Is there a Mailr app in the Jobber App Marketplace?
No. You build a custom integration in Jobber's Developer Center and call Mailr's REST API from it. To hear back, add a second route on the same receiver for Mailr's postcard.mailed webhook, or check a piece with GET /v1/postcards/{id}.
Can I do this without writing a receiver?
Yes, with an automation tool. Zapier's Jobber app has job and quote triggers, and a Webhooks by Zapier step can POST the address to Mailr with your key. Make and n8n work the same way with an HTTP step.
Will a duplicate webhook mail the card twice?
Not within 24 hours: the Idempotency-Key built from the itemId returns the first postcard instead of printing another. Save the postcard id with the job to skip later repeats.
Can I mail the neighbors around a finished job?
Only from a list you own or buy. Mailr mails the addresses you send, as single pieces or batches of up to 1,000, and doesn't sell lists or look up neighbors.