Direct mail API for developers and growth teams. Read the docs →

Direct mail API for Housecall Pro

Direct mail API for Housecall Pro: turn on the Webhooks app, point it at a small receiver, and each job.completed or estimate.sent event becomes a postcard that Mailr prints and mails to the job's address. Housecall Pro puts the customer and address in the event, so no second API call is needed.

What to mail from Housecall Pro

When this happensMail this
job.completedA review card a few days later, naming the job type, with a short link to your review page. (Review request)
estimate.sent, with no estimate.copy_to_job for it 7 days laterA 6x9 follow-up card with the estimate number and the number to book.
job.completed where job_fields.job_type.name is an install typeAn 8.5x11 letter with the install date and the date to register the equipment with the manufacturer.
Each spring and fall: jobs from 11 to 13 months ago (GET /jobs)A 6x9 tune-up reminder, sent as batches of up to 1,000.
A crew needs job-site signs (your own reorder, not a Housecall Pro event)Not mailed: 18x24 yard signs with H-stakes ordered with POST /v1/prints and shipped to the shop.

Set it up

  1. Check the plan. Housecall Pro's help center says the API and the Webhooks app are only on the MAX plan (XL in older plan names). On Essentials or Essentials+, use Housecall Pro's Zapier integration instead: its Job Finished trigger and a Webhooks by Zapier step that posts to Mailr.
  2. Turn on webhooks. In Housecall Pro, go to My Apps > All Apps and open Webhooks. Turn it on, enter your receiver's URL and save; Housecall Pro returns a signing secret, so copy it. Then choose the events: job.completed, estimate.sent and estimate.copy_to_job.
  3. Verify each request. Every event carries Api-Timestamp and Api-Signature headers. Build timestamp + "." + the raw body, compute an HMAC-SHA256 with the signing secret, and compare it with Api-Signature.
  4. Mail from the payload. The job event includes customer.first_name, customer.last_name and the job address (street, street_line_2, city, state, zip). POST them to Mailr with an Idempotency-Key built from the job id and save the postcard id.
  5. Make an API key for the seasonal batches. An Admin opens My Apps > All Apps > API Key Management and generates a key; read-only is enough. It's sent as Authorization: Token <key> to https://api.housecallpro.com.
  6. Test, then go live. Complete a test job with your mlr_test_ key in place and check the card in the Mailr dashboard; nothing prints. Then switch to your mlr_live_ key.

Code: the webhook receiver and a seasonal batch

// npm i express. Env: HCP_SIGNING_SECRET, MAILR_API_KEY
import crypto from "node:crypto";
import express from "express";

const app = express();
const MAILR = "https://api.mailr.dev/v1";
const FROM = { name: "Example Heating and Air", line1: "1200 W Example Rd", city: "Mesa", state: "AZ", zip: "85201" };

function signed(req) {
  const ts = req.get("Api-Timestamp") || "";
  const sig = req.get("Api-Signature") || "";
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // missing or older than 5 minutes
  const mac = crypto.createHmac("sha256", process.env.HCP_SIGNING_SECRET).update(`${ts}.${req.body}`).digest();
  // Housecall Pro doesn't say hex or base64, so accept either.
  return [mac.toString("hex"), mac.toString("base64")].some(
    (s) => s.length === sig.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(sig)),
  );
}

app.post("/hcp/webhooks", express.raw({ type: "*/*" }), async (req, res) => {
  if (!signed(req)) return res.sendStatus(401);
  const e = JSON.parse(req.body);
  res.sendStatus(200);
  try {
    if (e.event === "job.completed") await reviewCard(e.job);
    if (e.event === "estimate.sent") await recordEstimateSent(e.estimate); // your table: id, customer, address, sent time
    if (e.event === "estimate.copy_to_job") await markEstimateWon(e.estimate.id);
  } catch (err) {
    console.error(e.event, err.message);
  }
});

async function reviewCard(job) {
  const c = job.customer, a = job.address;
  if (!a?.street || !c?.first_name) return console.warn(`Job ${job.invoice_number}: no name or address`);
  const res = await fetch(`${MAILR}/postcards`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `hcp-review-${job.id}`,
    },
    body: JSON.stringify({
      size: "4x6",
      template: "tmpl_review_request",
      to: { name: `${c.first_name} ${c.last_name || ""}`.trim().slice(0, 40), line1: a.street, line2: a.street_line_2 || undefined, city: a.city, state: a.state, zip: a.zip },
      from: FROM,
      merge: {
        first_name: c.first_name.slice(0, 14),
        product_name: (job.job_fields?.job_type?.name || "service visit").slice(0, 22),
        review_url: "example.com/review",
      },
      description: `Review card, Housecall Pro job ${job.invoice_number}`,
    }),
  });
  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);
  • Housecall Pro's help center says the API and webhooks are only on the MAX plan, and only Admin users can generate or delete API keys. A key can read every record in the account.
  • Housecall Pro's webhook docs don't say whether the signature is hex or base64, so the sample accepts either. Its help article says the signing secret appears after you save the webhook URL, so copy it then.
  • Retries aren't documented. The Idempotency-Key from the job id makes a repeated job.completed return the first postcard for 24 hours instead of printing another.
  • GET /jobs pages with page and page_size and returns total_pages. Completed jobs show work_status as complete rated or complete unrated in the response. Over the rate limit the API answers 429 with a RateLimit-Reset header.
  • Mailr needs a two-letter state and a 5-digit or ZIP+4 code. An address Housecall Pro holds incompletely 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

Which Housecall Pro plan do I need?

MAX, according to Housecall Pro's help center, for both the API and the Webhooks app. Its Zapier integration is on Essentials, Essentials+ and MAX, and its Job Finished trigger can call Mailr through a Webhooks by Zapier step.

Do I need the API key for the review card?

No. The job.completed event already holds the customer's name and the job address, so the receiver only needs the signing secret and your Mailr key. The API key is for pulling past jobs for seasonal mailings.

How do I know an estimate wasn't sold?

Record each estimate.sent event, and mark it won when estimate.copy_to_job arrives for the same estimate (Housecall Pro sends that when the Pro creates a job from it). A nightly job mails a follow-up for estimates sent 7 or more days ago that were never copied to a job.

What does a tune-up 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 order the crew's yard signs here too?

Yes, with POST /v1/prints: 18x24 yard signs from 10, at $11.20 to $7.60 each on pay as you go depending on quantity, with H-stakes as an option. Pick them up in Phoenix or have them shipped UPS Ground, priced by destination.

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.
HOUSECALL PRO

Mail from Housecall Pro 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

Free price sheet

Get the price sheet by email

Every postcard, letter, mailer and print product on every plan, with postage included.

We’ll email you the price sheet. By continuing you agree to the Terms and Privacy Policy.

Download the template kit?

mailr-kit.zip · about 310 KB · 59 text files

Only HTML, JSON and Markdown files. No programs, scripts or macros, nothing that installs or runs.