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

Direct mail API for FieldEdge

Direct mail API for FieldEdge: register one webhook with FieldEdge's Open API, and when a work order is completed your receiver reads the work order and the customer, then sends the service address to Mailr, which prints and mails the card. Service agreements and installed equipment feed the seasonal and warranty mail.

What to mail from FieldEdge

When this happensMail this
work-order.completeA review card a few days later, naming the task, with a short link to your review page. (Review request)
quote.pending, and GET /v1/quotes/{quoteId} still says Pending 7 days laterAn 8.5x11 letter restating the quote and the number to call before it expires.
Agreements whose nextServiceDate is in the next 30 days (GET /v1/agreements)A 6x9 card naming the plan and asking the member to book the visit, sent as batches of up to 1,000.
Equipment installed this week (GET /v1/equipment, installDate)An 8.5x11 letter with the make, model, install date and parts warranty end date.
A tech needs equipment stickers (your own reorder, not a FieldEdge event)Not mailed: 2.5x2.5 vinyl stickers with your logo and phone, ordered with POST /v1/prints.

Set it up

  1. Request API access. FieldEdge's developer portal has a Customer API Access request form for members (contractors building their own integration); partners email FieldEdge's integrations team. Once your app is provisioned in the FieldEdge Marketplace (partners.fieldedge.com), copy its client ID and client secret, and find your tenant ID in FieldEdge.
  2. Get a token. POST client_id, client_secret, target_id (your tenant ID) and grant_type=client_credentials, form-encoded, to https://fieldedge.withgobo.com/oauth/token. The token lasts 28,800 seconds (8 hours) and goes in Authorization: Bearer.
  3. Register the webhook. POST https://api.fieldedge.com/open-api/v1/webhook with a callbackUrl (and any headers you want sent back to you). The response returns an HMAC secret once; store it. One registration receives every event type.
  4. Verify each delivery. Each delivery has X-FieldEdge-Signature: sha256=<hex>, an HMAC-SHA256 of the body with that secret. Events hold only ids, so on work-order.complete call GET /v1/work-orders/{workOrderId} for the service address and GET /v1/customers/id/{customerId} for the name.
  5. Send it to Mailr. POST the address to /v1/postcards with an Idempotency-Key built from the work order id, and save the postcard id. Check a piece later with GET /v1/postcards/{id}, or add a Mailr webhook endpoint for postcard.mailed.
  6. Test, then go live. Complete a work order 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 maintenance-agreement batch

// npm i express. Env: FE_CLIENT_ID, FE_CLIENT_SECRET, FE_TENANT_ID, FE_WEBHOOK_SECRET, MAILR_API_KEY
import crypto from "node:crypto";
import express from "express";

const FE = "https://api.fieldedge.com/open-api";
const app = express();
let token = { value: "", until: 0 };

async function feToken() {
  if (Date.now() < token.until) return token.value;
  const res = await fetch("https://fieldedge.withgobo.com/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      client_id: process.env.FE_CLIENT_ID,
      client_secret: process.env.FE_CLIENT_SECRET,
      target_id: process.env.FE_TENANT_ID,
      grant_type: "client_credentials",
    }),
  });
  const t = await res.json();
  token = { value: t.access_token, until: Date.now() + (t.expires_in - 300) * 1000 };
  return token.value;
}

const fe = async (path) => {
  const res = await fetch(FE + path, { headers: { Authorization: `Bearer ${await feToken()}` } });
  if (!res.ok) throw new Error(`FieldEdge ${path}: ${res.status}`);
  return res.json();
};

app.post("/fieldedge/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  const sent = req.get("X-FieldEdge-Signature") || "";
  const ours = "sha256=" + crypto.createHmac("sha256", process.env.FE_WEBHOOK_SECRET).update(req.body).digest("hex");
  if (sent.length !== ours.length || !crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(ours))) return res.sendStatus(401);
  res.sendStatus(200);
  const e = JSON.parse(req.body);
  if (e.type === "work-order.complete") reviewCard(e.data.workOrderId).catch((err) => console.error(e.id, err.message));
  if (e.type === "quote.pending") recordPendingQuote(e.data.quoteId); // your table; a nightly job checks it 7 days later
});

async function reviewCard(workOrderId) {
  const wo = await fe(`/v1/work-orders/${workOrderId}`);
  const c = await fe(`/v1/customers/id/${wo.customerId}`);
  const a = wo.serviceAddress;
  if (!a?.addressLine1 || !c.firstName) return console.warn(`${wo.workOrderNumber}: no name or address`);

  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": `fe-review-${workOrderId}`,
    },
    body: JSON.stringify({
      size: "4x6",
      template: "tmpl_review_request",
      to: {
        name: `${c.firstName} ${c.lastName || ""}`.trim().slice(0, 40),
        company: c.companyName ? c.companyName.slice(0, 40) : undefined,
        line1: a.addressLine1, line2: a.addressLine2 || undefined, city: a.city, state: a.state, zip: a.postalCode,
      },
      from: { name: "Example Heating and Air", line1: "1200 W Example Rd", city: "Mesa", state: "AZ", zip: "85201" },
      merge: {
        first_name: c.firstName.slice(0, 14),
        product_name: (wo.workOrderInformation?.taskName || "service visit").slice(0, 22),
        review_url: "example.com/review",
      },
      description: `Review card, FieldEdge ${wo.workOrderNumber}`,
    }),
  });
  const piece = await res.json();
  if (!res.ok) throw new Error(`Mailr ${res.status}: ${piece.error.message}`);
  await saveMailrId(workOrderId, piece.id);
}

app.listen(3000);
  • FieldEdge's developer portal is gated: members request access with its Customer API Access form, and partners email FieldEdge. Each endpoint needs a scope, such as workorders:read, customers:read, equipment:read or webhooks:write for registering the webhook.
  • Rate limits are per partner: 100 requests in any 60 seconds (429 with Retry-After) and 1,000 per clock hour (403 with a quota message and no Retry-After). Every key and every customer you serve shares that allowance.
  • Webhook events are notification-only: they carry the id and number of what changed, never the record. Each event costs at least one GET, which counts against the hourly quota.
  • quote.pending fires when a quote is created or goes back to Pending, not when it's saved without a status change. The quote id equals the work order id. quote.accepted, quote.rejected and quote.expired are lead events, sent for partner leads.
  • Rotating the HMAC secret (a separate endpoint) replaces it at once, so update FE_WEBHOOK_SECRET in the same deploy.
  • One with a missing street or a state that isn't two letters fails with a 422 naming the field, and nothing is 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

Does FieldEdge have webhooks?

Yes, through its Open API. One registration receives work order events (created, scheduled, complete, finalized and more), invoice, customer and quote events. Each event holds only ids, so your receiver reads the work order and customer before calling Mailr.

Can a contractor use the API, or only partners?

Both. FieldEdge serves members, contractors building private integrations for their own business, and partners building public apps. Members request access with the Customer API Access form and get credentials from the FieldEdge Marketplace.

How do I mail maintenance-agreement members?

GET /v1/agreements with afterNextServiceDate and beforeNextServiceDate returns agreements with a visit coming up, with the plan name. Look up each customer's address, then send them as batches of up to 1,000. A 6x9 postcard is $0.89 on pay as you go, postage included.

Can I send a warranty letter after an install?

Yes. GET /v1/equipment returns installed units with manufacturer, model, installDate and partsWarrantyExpirationDate. Mail an 8.5x11 letter with those, using an Idempotency-Key built from the equipment id.

Can I order equipment stickers through Mailr?

Yes, with POST /v1/prints: vinyl stickers from 50 (2.5x2.5 is a common size for a furnace or water heater), cut to the shape you pick, picked up in Phoenix 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.
FIELDEDGE

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