Direct mail API for AccuLynx
Direct mail API for AccuLynx: subscribe to the job.milestone.current_changed webhook, read the job's address and primary contact from the AccuLynx API, and send them to Mailr, which prints the card or letter, pays the postage and mails it.
What to mail from AccuLynx
| When this happens | Mail this |
|---|---|
| job.milestone.current_changed, new milestone Completed | A thank-you card with a short link to your review page. (Review request) |
| job.milestone.current_changed, new milestone Completed, on a roof replacement | An 8.5x11 warranty letter with the completion date and the date to register the manufacturer's warranty. |
| A job still in Prospect 14 days after it got there (Get Jobs: milestones=prospect, dateFilterType=MilestoneDate) | An 8.5x11 letter restating the scope and the number to call. |
| A hail or wind storm: your AccuLynx contacts in the hit ZIP codes, plus a list you buy | A 6x9 inspection card, sent as batches of up to 1,000. |
| job.milestone.current_changed, new milestone Approved (the crew is coming) | Not mailed: count approved jobs each week and reorder 18x24 yard signs with H-stakes through POST /v1/prints. |
Set it up
- Create an API key. On your AccuLynx account, create and name an API key. It's sent as Authorization: Bearer <key> to both the API (https://api.acculynx.com/api/v2) and the Webhooks API (https://api.acculynx.com/webhooks/v2).
- Check the topic name. GET /webhooks/v2/topics lists the topics you can subscribe to. The milestone topic in the reference is job.milestone.current_changed; use the name exactly as the topics list returns it.
- Create the subscription. POST /webhooks/v2/subscriptions with consumerUrl (a public HTTPS URL), techContact (an email AccuLynx writes to about the subscription) and topicNames. The consumer URL can't be changed later, so put a long random token in its path now; AccuLynx's reference documents no signature header.
- Send a test event. POST /webhooks/v2/subscriptions/{subscriptionId}/test-event with a topicName. AccuLynx sends a sample of that event to your URL, so you can check your receiver before a real job moves.
- Look up the job and mail. The event holds the job id and the new milestone's name and date. GET /api/v2/jobs/{id}?includes=contact returns locationAddress and the contacts, one marked isPrimary. POST to Mailr with an Idempotency-Key built from the job id.
- Go live. Run the test event with your mlr_test_ key and check the pieces in the Mailr dashboard; nothing prints. Then switch to your mlr_live_ key.
Code: the subscription, the receiver and prospect follow-ups
# The topics you can subscribe to
curl https://api.acculynx.com/webhooks/v2/topics \
-H "Authorization: Bearer $ACCULYNX_API_KEY"
# Subscribe. The consumer URL can't be changed later; the token in its path is your only check.
curl https://api.acculynx.com/webhooks/v2/subscriptions \
-H "Authorization: Bearer $ACCULYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"consumerUrl": "https://hooks.example.com/acculynx/7f3c9e1a5b2d48c6a0e4f1b9d2c7a8e5",
"techContact": "dev@example.com",
"topicNames": ["job.milestone.current_changed"],
"integrationType": "Api"
}'
# Send a sample event to the URL (use the subscriptionId from the response above)
curl https://api.acculynx.com/webhooks/v2/subscriptions/$SUBSCRIPTION_ID/test-event \
-H "Authorization: Bearer $ACCULYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "topicName": "job.milestone.current_changed" }'
# Try the Mailr side by hand with your test key (nothing prints), keyed on the AccuLynx job id
curl https://api.mailr.dev/v1/postcards \
-H "Authorization: Bearer $MAILR_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: acculynx-thanks-d5d604ad-18a5-4659-af86-aecaec161c2e" \
-d '{
"size": "4x6",
"template": "tmpl_review_request",
"to": { "name": "Ana Ortiz", "line1": "2140 Sample Ave", "city": "Mesa", "state": "AZ", "zip": "85201" },
"from": { "name": "Example Roofing", "line1": "1200 W Example Rd", "city": "Mesa", "state": "AZ", "zip": "85201" },
"merge": { "first_name": "Ana", "product_name": "new roof", "review_url": "example.com/review" }
}'- AccuLynx's own getting-started page names this use: sending job contacts to marketing software for a postcard mailing when jobs reach a milestone.
- The webhook carries ids, the milestone name and date and API links, not the address. One GET /api/v2/jobs/{id}?includes=contact returns locationAddress (street1, street2, city, state.abbreviation, zipCode) and the contacts.
- The Webhooks API reference documents no signature header or shared secret on deliveries, so keep a long random token in the consumer URL path and treat each event as a prompt to re-read the job from the API.
- Rate limits: 30 requests a second per IP, then 10 a second per API key; over that, AccuLynx answers 429 for anywhere from 30 seconds to a few minutes. Get Jobs returns at most 25 jobs a page.
- AccuLynx supports its API only through the Contact Us form on its developer site, not through its customer support team.
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 AccuLynx event means a roof is finished?
job.milestone.current_changed with the new milestone's name set to Completed. AccuLynx's milestones run Lead, Prospect, Approved, Completed, Invoiced, Closed and Cancelled, so you can also mail on Approved or Invoiced.
Can I mail homeowners after a hail storm?
Yes, to addresses you have: your AccuLynx contacts in the hit ZIP codes and any list you buy for the area. Mailr doesn't sell lists; send verify: true to check each address against USPS data. Send up to 1,000 recipients per batch; a batch is 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.
Can I do this without writing code?
AccuLynx suggests its Zapier integration for teams without developers, and Zapier lists a milestone trigger for AccuLynx jobs. A Webhooks by Zapier step can then POST the address to Mailr with your key.
Do yard signs come from the same API?
Yes. POST /v1/prints orders 18x24 yard signs from 10, $11.20 to $7.60 each on pay as you go depending on quantity, with H-stakes as an option, picked up in Phoenix or shipped UPS Ground, priced by destination.