Direct mail API for Service Fusion
Direct mail API for Service Fusion: Service Fusion's API has no webhooks, so a scheduled job reads closed jobs, estimates and equipment with the API's filters and sends each address to Mailr, which prints the card or letter, pays the postage and mails it.
What to mail from Service Fusion
| When this happens | Mail this |
|---|---|
| Jobs closed since the last run (GET /v1/jobs, filters[closed_date][gte]) | A review card a few days later, naming the job category, with a short link to your review page. (Review request) |
| Estimates in your open status created 7 days ago (GET /v1/estimates, filters[status]) | An 8.5x11 letter restating the estimate and the number to call. |
| Equipment on a closed job's customer with an install_date in the last 7 days (GET /v1/customers/{id}/equipment) | An 8.5x11 letter with the make, model, install date and warranty date. |
| Each spring and fall: maintenance jobs that ended 11 to 13 months ago (filters[category], filters[end_date]) | A 6x9 tune-up reminder, sent as batches of up to 1,000. |
| The trucks need leave-behinds (your own reorder, not a Service Fusion event) | Not mailed: 4x9 rack cards ordered with POST /v1/prints and shipped to the shop. |
Set it up
- Get API credentials. In Service Fusion, open the OAuth Consumer page in developer settings (admin.servicefusion.com/developerSettings/oauthConsumer) and copy the client ID and client secret. Service Fusion's API docs don't say which plans include the API, so check with them if the page is missing.
- Get a token. POST {"grant_type": "client_credentials", "client_id": ..., "client_secret": ...} as JSON to https://api.servicefusion.com/oauth/access_token. The access token lasts 3,600 seconds and comes with a refresh token; send it as Authorization: Bearer.
- Poll closed jobs. Every hour, GET https://api.servicefusion.com/v1/jobs with filters[closed_date][gte] set to the last run (RFC 3339), per-page=50 and page. Each job carries contact_first_name, contact_last_name, street_1, street_2, city, state_prov and postal_code.
- Send each job to Mailr. POST the address to /v1/postcards with an Idempotency-Key built from the job id, save the postcard id, and only then move the last-run time forward.
- Add the scheduled mailings. Pull estimates and maintenance jobs with the same filters on a weekly schedule and send them as batches of up to 1,000 with POST /v1/batches.
- Test, then go live. Run it with your mlr_test_ key and check the pieces in the Mailr dashboard; nothing prints. Then switch to your mlr_live_ key.
Code: closed jobs to review cards, and a tune-up batch
// Run hourly. Node 18+. Env: SF_CLIENT_ID, SF_CLIENT_SECRET, MAILR_API_KEY
const SF = "https://api.servicefusion.com";
async function sfToken() {
const res = await fetch(`${SF}/oauth/access_token`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ grant_type: "client_credentials", client_id: process.env.SF_CLIENT_ID, client_secret: process.env.SF_CLIENT_SECRET }),
});
if (!res.ok) throw new Error(`Service Fusion token: ${res.status}`);
return (await res.json()).access_token; // good for 3,600 seconds
}
export async function mailClosedJobs(since /* RFC 3339, e.g. "2026-11-19T08:00:00-07:00" */) {
const token = await sfToken();
for (let page = 1; ; page++) {
const q = new URLSearchParams({ "filters[closed_date][gte]": since, "per-page": "50", page: String(page), sort: "closed_at" });
const res = await fetch(`${SF}/v1/jobs?${q}`, { headers: { Authorization: `Bearer ${token}` } });
if (!res.ok) throw new Error(`Service Fusion jobs: ${res.status}`); // 429 past 60 requests a minute
const { items, _meta } = await res.json();
for (const job of items) {
const first = (job.contact_first_name || "").trim();
if (!job.street_1 || !/^[A-Z]{2}$/i.test(job.state_prov || "") || !first) continue;
const mail = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `sf-review-${job.id}`,
},
body: JSON.stringify({
size: "4x6",
template: "tmpl_review_request",
to: {
name: `${first} ${job.contact_last_name || ""}`.trim().slice(0, 40),
line1: job.street_1, line2: job.street_2 || undefined, city: job.city, state: job.state_prov, zip: job.postal_code,
},
from: { name: "Example Plumbing", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
merge: {
first_name: first.slice(0, 14),
product_name: (job.category || "service visit").slice(0, 22),
review_url: "example.com/review",
},
description: `Review card, Service Fusion job ${job.number}`,
}),
});
const piece = await mail.json();
if (!mail.ok) { console.error(job.number, piece.error.message); continue; }
await saveMailrId(job.id, piece.id); // your own table
}
if (_meta.currentPage >= _meta.pageCount) break;
}
}- Service Fusion's API reference documents reading customers, jobs, estimates, invoices and equipment, creating customers, jobs and estimates, and no webhooks. Poll on a schedule.
- Each access token is limited to 60 requests a minute. Responses carry X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset, and going over returns 429.
- Lists return items plus _meta (totalCount, pageCount, currentPage, perPage), with per-page from 1 to 50. Use fields to return only the columns you mail from.
- Status, category and source filters are a full match on the names in your account, so copy them exactly from Service Fusion.
- Equipment records carry make, model, serial_number, install_date and warranty_date, which is what a warranty registration letter needs.
- Add verify: true to have Mailr check each address against USPS data. A job with a missing street or a state that isn't two letters comes back as a 422 naming the field, and nothing is charged.
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 Service Fusion have webhooks?
Not in its public API reference, which documents list, get and create operations. A scheduled poll with filters[closed_date][gte] catches every closed job, and the Idempotency-Key stops a re-run from mailing twice.
Which address does a job use?
The job's own location: street_1, street_2, city, state_prov and postal_code, with the contact's first and last name. That's the service address, which may differ from the customer's billing address.
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. A batch of up to 1,000 is checked and paid in one request, all or nothing.
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.
Can the same code order rack cards and stickers?
Yes. POST /v1/prints orders rack cards, vinyl stickers and 18x24 yard signs, printed in Phoenix and picked up there or shipped UPS Ground, priced by destination. Test orders are free and never print.