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

Direct mail API for ServiceTitan

Direct mail API for ServiceTitan: a scheduled job, written by the contractor's developer or the agency that runs its marketing, reads completed jobs, open estimates and memberships from ServiceTitan's APIs and sends each service address to Mailr, which prints the postcard or flat, pays the postage and mails it. ServiceTitan's V2 webhooks are in beta and their docs are shown only to accounts with access, so the job polls. ServiceTitan also sells postcards inside Marketing Pro; the questions at the end cover when that is the simpler choice.

What to mail from ServiceTitan

When this happensMail this
A job reaches Completed (Jobs API: jobStatus=Completed, completedOnOrAfter your last run)A 4x6 review card naming the work, with a short link to your review page. It lands a few days after the visit. (Review request)
An estimate is still Open 7 days after it was created (Estimates API: status=Open)An 8.5x11 letter, mailed flat, that restates the option, the price and the number to call.
An Active membership's end date (to) is 30 days away (Memberships API)A 6x11 renewal card listing the visits and discounts the plan covered.
A completed job has installed equipment attached (equipmentIds on the job)An 8.5x11 letter with the model, the install date and the date to register it with the manufacturer.
Each spring and fall: customers whose last tune-up job was completed 11 to 13 months agoA 6x9 tune-up reminder, sent as batches of up to 1,000.
Data from outside ServiceTitan, such as a utility rebate list or a hail report by ZIP code, matched to your customers' locations in your own codeA 6x11 card to the customers in those ZIP codes, sent as batches of up to 1,000.
The trucks run low on leave-behinds, or a crew starts a job (your own count or schedule, not a ServiceTitan event)Not mailed: 18x24 yard signs, 4.25x11 door-hanger-size cards and 2.5x2.5 equipment stickers ordered with POST /v1/prints and shipped to the shop.

Set it up

  1. Register an app. Whoever writes the job, the contractor's developer or the agency's, signs in to ServiceTitan's developer portal (developer.servicetitan.io) as a user of the organization and registers an app with read scopes for jobs (tn.jpm.jobs:r), customers (tn.crm.customers:r), locations (tn.crm.locations:r), estimates (tn.sal.estimates:r) and memberships (tn.mem.memberships:r). The portal gives the app an application key, sent as the ST-App-Key header.
  2. Connect it to the tenant. A ServiceTitan admin connects the app under Settings > Integrations > API Application Access and generates the client ID and client secret. Note the tenant ID: every API path includes it.
  3. Get a token on each run. POST grant_type=client_credentials with the client ID and secret, form-encoded, to https://auth.servicetitan.io/connect/token. The token lasts 900 seconds, so request a new one at the start of each run.
  4. Poll for finished work. Every hour, GET /jpm/v2/tenant/{tenant}/jobs with jobStatus=Completed and completedOnOrAfter set to the last run. For each job, read the customer (name and the doNotMail flag) and the job's location, which holds the service address.
  5. Send it to Mailr. Skip customers flagged do not mail. POST the address to /v1/postcards with an Idempotency-Key built from the job id, save the returned postcard id against the job in your own database, and move the last-run time forward only after the run finishes.
  6. Hear back when it mails. Add a webhook endpoint: POST /v1/webhooks with your test key adds a test endpoint, and live endpoints are added in the Mailr dashboard under Developers > Webhooks. Each signed event, such as postcard.mailed, carries the postcard id and status but no names or addresses, so look the job up by the postcard id you saved.
  7. Test, then go live. Run it with your mlr_test_ key and watch the pieces in the Mailr dashboard; test pieces are free, never print and move through every status in about eight minutes. Then set MAILR_API_KEY to your mlr_live_ key.

ServiceTitan API to Mailr: completed jobs and open estimates

// Run hourly from cron or a scheduled function. Node 18+.
// Env: ST_TENANT, ST_APP_KEY, ST_CLIENT_ID, ST_CLIENT_SECRET, MAILR_API_KEY
const ST = "https://api.servicetitan.io";
const tenant = process.env.ST_TENANT;
// Your job type ids → a short name for the card (22 characters max)
const WORK = { 1234567: "AC tune-up", 1234568: "new water heater" };

async function stToken() {
  const res = await fetch("https://auth.servicetitan.io/connect/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.ST_CLIENT_ID,
      client_secret: process.env.ST_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`ServiceTitan token: ${res.status}`);
  return (await res.json()).access_token; // good for 900 seconds
}

async function st(token, path) {
  const res = await fetch(ST + path, { headers: { Authorization: token, "ST-App-Key": process.env.ST_APP_KEY } });
  if (!res.ok) throw new Error(`ServiceTitan ${path}: ${res.status}`);
  return res.json();
}

export async function mailReviewCards(since /* ISO time of the last run */) {
  const token = await stToken();
  for (let page = 1; ; page++) {
    const q = new URLSearchParams({ jobStatus: "Completed", completedOnOrAfter: since, page: String(page), pageSize: "50" });
    const jobs = await st(token, `/jpm/v2/tenant/${tenant}/jobs?${q}`);
    for (const job of jobs.data) {
      const customer = await st(token, `/crm/v2/tenant/${tenant}/customers/${job.customerId}`);
      if (customer.doNotMail) continue;
      const { address: a } = await st(token, `/crm/v2/tenant/${tenant}/locations/${job.locationId}`);

      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": `st-review-${job.id}`,
        },
        body: JSON.stringify({
          size: "4x6",
          template: "tmpl_review_request",
          to: { name: customer.name.slice(0, 40), line1: a.street, line2: a.unit || undefined, city: a.city, state: a.state, zip: a.zip },
          from: { name: "Example Heating and Air", line1: "1200 W Example Rd", city: "Mesa", state: "AZ", zip: "85201" },
          merge: {
            first_name: customer.name.split(" ")[0].slice(0, 14),
            product_name: WORK[job.jobTypeId] ?? "service visit",
            review_url: "example.com/review",
          },
          description: `Review card, ServiceTitan job ${job.jobNumber}`,
        }),
      });
      const piece = await res.json();
      if (!res.ok) { console.error(job.id, piece.error.message); continue; } // a 422 names the field to fix
      await saveMailrId(job.id, piece.id); // your own table: job id → postcard id
    }
    if (!jobs.hasMore) break;
  }
}
  • ServiceTitan's developer FAQ says new subscriptions to its first webhook version are restricted, and the V2 Webhooks (Beta) page only appears for accounts with access. Scheduling Pro webhooks exist but cover online booking sessions only, and that feature is in private preview. Polling the Jobs API is the route open to every tenant.
  • The default rate limit is 600 calls per 10 seconds per app per tenant. Reporting APIs allow the same report once a minute per tenant.
  • For large backfills, use the export endpoints (for example /jpm/v2/tenant/{tenant}/export/jobs). Each response returns a continueFrom token for the next call; records appear there 15 minutes after they change unless you pass includeRecentChanges=true, which can return duplicates.
  • Customers carry a doNotMail flag and a type of Residential or Commercial. Check doNotMail before every mailing, and use type to send commercial accounts a letter instead of a card.
  • Mailr rejects a location with a missing street or a state that isn't a two-letter code with a 422 naming the field, and nothing is charged. Add "verify": true to also check each address against USPS data before charging; an undeliverable one fails the same way, and deliverable ones are mailed in their corrected form.
  • Flats mail without an envelope, so the option and price on an estimate letter can be read by anyone who handles it. Leave the price off if a customer would mind.
  • Live pieces report through mailed, when they are handed to USPS. There are no USPS delivery scans for live mail, so mailed is the last status your code will see.
  • Agencies running several contractors: keep each contractor's tenant ID, client ID and secret separate, put that contractor's return address in from on every piece, and run each tenant's poll on its own schedule, since the rate limit is per app per tenant.

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 ServiceTitan API have webhooks for completed jobs?

Not for most accounts today. ServiceTitan's V2 webhooks are in beta, and the docs for them are only shown to accounts with access. Polling the Jobs API with jobStatus=Completed and completedOnOrAfter catches every finished job, and the Idempotency-Key keeps a re-run from mailing twice.

When is ServiceTitan Marketing Pro the simpler choice?

When the contractor runs on ServiceTitan alone, wants 4x6 or 6x9 postcards and has nobody to own code. Marketing Pro builds audiences from live ServiceTitan data such as unsold estimates, equipment age and warranty dates, builds prospect audiences from property data, runs automated postcard sequences that can stop when a call is created or a job is booked, mails First-Class, and ties each campaign to jobs and revenue inside ServiceTitan. Mailr doesn't write results back to ServiceTitan, doesn't sell prospect lists and mails USPS Marketing Mail, not First-Class, so with Mailr the list and the reporting are yours to build.

Why would an agency mail through a direct mail API instead of Marketing Pro?

Because its clients aren't all on ServiceTitan. Marketing Pro runs inside each contractor's ServiceTitan account. An agency with HVAC clients on ServiceTitan, plumbers on Housecall Pro and roofers on JobNimbus or AccuLynx can run all of them through the same Mailr code and the same published per-piece prices, with each contractor's return address on its own pieces. The jobs and their triggers stay in the agency's own repository.

What does building on the API add for a ServiceTitan contractor?

Triggers from data ServiceTitan doesn't hold, such as a utility rebate list, building permits or a hail report by ZIP code, matched to ServiceTitan locations in your code. Per-customer content: Mailr fills the {{tags}} in your HTML for each piece, so a card can name the technician, the equipment model or the estimate option; ServiceTitan's help articles describe uploaded postcard images and plain-text fields, and don't document per-customer merge fields. More mail formats: 6x11 postcards, 8.5x11 and 8.5x14 flats and 11x17 folded mailers. And printed items from the same API: 18x24 yard signs, 4.25x11 door-hanger-size cards, rack cards and equipment stickers.

Can a contractor use Marketing Pro and Mailr together?

Yes. One split is Marketing Pro for postcard campaigns to the audiences it builds, and a Mailr job for estimate letters, folded mailers, yard signs and anything triggered by outside data. Log what each one sends so a customer doesn't get two pieces about the same job in one week.

Is there a Mailr app in the ServiceTitan Marketplace?

No. Your code, or the agency or consultant who runs the account, registers an app in ServiceTitan's developer portal and calls Mailr's REST API. Mailr reports back through signed webhooks: postcard.mailed and the other status events go to an endpoint you add, carrying the piece id and status, or check a piece with GET /v1/postcards/{id}.

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. Send that list as a batch of up to 1,000 per request.

What does a spring tune-up mailing cost?

A 6x9 postcard is $0.89 on pay as you go and $0.69 on the Agency plan ($149 a month), printing and USPS Marketing Mail postage included. So 5,000 tune-up cards cost $4,450.00 on pay as you go or $3,450.00 on Agency. Test pieces are free.

Can the same code order job-site signs and door-hanger-size cards?

Yes. POST /v1/prints orders 18x24 yard signs (from 10, $11.20 down to $7.60 each on pay as you go as the quantity goes up), 4.25x11 door-hanger-size cards (from 100, $0.37 each), rack cards and equipment stickers. They're printed in Phoenix and picked up there or 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.
SERVICETITAN

Mail from ServiceTitan 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.