Direct mail API for JobNimbus
Direct mail API for JobNimbus: read jobs whose status changed from the JobNimbus API, or catch them with Zapier's Job Modified trigger, and send the job's address to Mailr, which prints and mails the card or letter. Storm campaigns go out as batches of up to 1,000 from your own contacts and any list you buy.
What to mail from JobNimbus
| When this happens | Mail this |
|---|---|
| A job's status changes to your finished status, such as Paid & Closed (date_status_change, status_name) | A thank-you card with a short link to your review page. (Review request) |
| The same status change on a roof replacement | An 8.5x11 warranty letter with the date the roof was finished and the date to register the manufacturer's warranty. |
| A job has sat in your Estimate Sent status for 7 days (date_status_change) | An 8.5x11 letter restating the scope and the number to call, while the adjuster's numbers are fresh. |
| A hail or wind storm: your JobNimbus contacts in the hit ZIP codes, plus a list you buy for those ZIPs | A 6x9 card offering an inspection, sent as batches of up to 1,000. |
| A roof is finished: the neighbors on that street, from a list you own or buy | A 6x9 card naming the work done nearby and the number to book. |
| A crew starts a new job (your own reorder, not a JobNimbus event) | Not mailed: 18x24 yard signs with H-stakes ordered with POST /v1/prints. |
Set it up
- Create an API key. In JobNimbus, open Settings > API and select + Create New. Name it Mailr and pick an Access Profile that can read contacts and jobs; the key gets that profile's permissions. Copy the key on that screen, since JobNimbus shows it once, and note the expiry date: new keys expire one year after they're created.
- Note your status names. Statuses come from your own workflows, so write down the exact status_name values that mean finished and estimate sent, for example Paid & Closed and Estimate Sent.
- Poll for status changes. Every hour, GET https://app.jobnimbus.com/api1/jobs with a filter on date_status_change since the last run, sent as Authorization: Bearer <key>. Check status_name in your code and read the primary contact for the first name.
- Send each job to Mailr. POST the job's address (address_line1, address_line2, city, state_text, zip) to /v1/postcards or /v1/flats with an Idempotency-Key built from the job's jnid, and save the returned id.
- Or use Zapier. Without code: JobNimbus's Job Modified trigger, a Filter step on the status name, then a Webhooks by Zapier custom request that POSTs to Mailr with your key. Job Modified fires on every edit, so the poller is safer for mail that must go once.
- Send storm campaigns as batches. After a storm, pull contacts in the hit ZIP codes, add the list you bought, remove duplicate addresses and send up to 1,000 recipients per POST /v1/batches. Test with your mlr_test_ key first; nothing prints.
Code: status changes, a storm batch and the Zapier route
# Run hourly. Env: JOBNIMBUS_API_KEY, MAILR_API_KEY
# mail/warranty/front.html and back.html: your 8.5x11 design with {{first_name}} and {{finished_on}}.
import datetime as dt
import json
import os
import requests
JN = "https://app.jobnimbus.com/api1"
jn = {"Authorization": f"Bearer {os.environ['JOBNIMBUS_API_KEY']}"}
mailr = "https://api.mailr.dev/v1"
DONE = "Paid & Closed" # the exact status name in your workflow
SHOP = {"name": "Example Roofing", "line1": "1200 W Example Rd", "city": "Mesa", "state": "AZ", "zip": "85201"}
since = load_last_run() # your storage: unix seconds of the last run
def send(path, key, body):
r = requests.post(f"{mailr}/{path}", json=body, timeout=30, headers={
"Authorization": f"Bearer {os.environ['MAILR_API_KEY']}", "Idempotency-Key": key})
print(key, r.status_code, r.json().get("id") or r.json()["error"]["message"])
flt = json.dumps({"must": [{"range": {"date_status_change": {"gte": since}}}]})
start = 0
while True:
page = requests.get(f"{JN}/jobs", headers=jn, params={"filter": flt, "size": 1000, "from": start}, timeout=60).json()
for job in page["results"]:
if job.get("status_name") != DONE or not job.get("address_line1") or not job.get("primary"):
continue
contact = requests.get(f"{JN}/contacts/{job['primary']['id']}", headers=jn, timeout=30).json()
first = (contact.get("first_name") or "").strip()
if not first:
continue
finished = dt.date.fromtimestamp(job["date_status_change"])
to = {"name": f"{first} {contact.get('last_name') or ''}".strip()[:40], "line1": job["address_line1"],
"line2": job.get("address_line2"), "city": job["city"], "state": job["state_text"], "zip": job["zip"]}
send("postcards", f"jn-thanks-{job['jnid']}", {
"size": "4x6", "template": "tmpl_review_request", "to": to, "from": SHOP,
"merge": {"first_name": first[:14], "product_name": "new roof", "review_url": "example.com/review"},
"description": f"Thank-you card, job {job['number']}"})
send("flats", f"jn-warranty-{job['jnid']}", {
"size": "8.5x11", "to": to, "from": SHOP,
"front": open("mail/warranty/front.html").read(), "back": open("mail/warranty/back.html").read(),
"merge": {"first_name": first[:14], "finished_on": f"{finished:%B} {finished.day}, {finished:%Y}"},
"description": f"Warranty letter, job {job['number']}"})
start += len(page["results"])
if start >= page["count"] or not page["results"]:
break- JobNimbus's own Webhook automation action exists, but its help article doesn't document the method, headers or payload, and custom fields aren't included. The API poll or Zapier is the documented route.
- New API keys expire one year after they're created, and keys made before September 18, 2026 are legacy keys that also expire. When the integration stops connecting, make a new key and swap it in.
- Use the full API key, not the Key ID shown in the key list; a Key ID gives an authentication failure.
- The jobs and contacts endpoints return up to 1,000 records per call (size), page with from, and take an Elasticsearch-style filter: a range on date_status_change or date_updated, or terms on jnid or zip.
- Zapier's Job Modified trigger fires on every edit to a job, and JobNimbus's Zapier actions can't update a job to mark it mailed. The Idempotency-Key stops repeats for 24 hours; after that, a later edit to a closed job would send again.
- Mailr doesn't sell lists; send verify: true to check each address against USPS data. Storm and neighbor mail goes to your own contacts or a list you buy, and an address with a missing street or a bad ZIP fails the whole batch with a 422 naming the recipient, before anything 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 JobNimbus send a webhook when a job's status changes?
Its automations have a Webhook action, but JobNimbus doesn't document that request's method, headers or format. The API exposes date_status_change and status_name on every job, so an hourly poll catches each change, and Zapier's Job Modified trigger with a status filter works without code.
Can I mail every house a storm hit?
Only addresses you have: your JobNimbus contacts in those ZIP codes and a list you buy for the area. Mailr doesn't sell lists. Send them as batches of up to 1,000; each batch is checked and paid in one request, all or nothing.
What does a storm mailing cost?
A 6x9 postcard is $0.89 on pay as you go, printing and postage included, and less on a plan. Test pieces are free and never print.
How do yard signs get to the crews?
Order them with POST /v1/prints: 18x24 signs from 10, $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 before you pay.
Will a re-run send a second thank-you card?
Not within 24 hours, because the Idempotency-Key from the job's jnid returns the first card. Save the returned id with the job, or keep the last-run time, so later runs skip jobs already mailed.