Direct mail for growth teams, with an API underneath. Read the docs →

Direct mail API for Perspective

Direct mail API for Perspective: when a visitor converts to a lead in a Perspective funnel, the New Lead webhook posts their answers to a small endpoint you host, and that endpoint asks Mailr to print and mail a postcard or letter to the address they entered. Each lead's contact id is the idempotency key, so one lead gets one piece however often the webhook fires.

What to mail from Perspective

When this happensMail this
New Lead (a funnel visitor converts to a lead)A postcard in your own design to the address from the funnel's form.
Funnel completed (the visitor went through every step)A letter on an 8.5x11 flat with the offer or quote their answers point to, in your own design.
Zapier's New Lead via Funnel or Make's Watch for New LeadsThe same postcard, sent from a Zap or scenario instead of your own endpoint.

Set it up

  1. Collect a mailing address in the funnel. Add Street, City and ZIP Code fields to a Form block (and Country if you take leads from abroad). Perspective's address fields have no state, so add a custom text field and set its identifier to state; Mailr needs a two-letter state and a 5-digit or ZIP+4 code. The street field holds the house number too.
  2. Deploy the endpoint. Deploy the Worker below with npx wrangler deploy. Set MAILR_API_KEY (a test key while you build) and HOOK_TOKEN, a long random string, with npx wrangler secret put. Save a return address in Mailr Settings so requests can leave out from.
  3. Add the webhook. In the funnel builder's Apps tab, add the webhook app with the trigger New Lead and the URL https://<your worker>/perspective/<HOOK_TOKEN>. Webhooks are on the Grow plan and up, or with the Premium Integration Suite, and a funnel can have up to 3 per trigger.
  4. Check one real payload. Go through the funnel with your own US address. The Worker logs every lead it skips, and Perspective lists failed deliveries under App events (the three-dot menu on the app's card). Confirm the identifiers match the ones in FIELDS before going further.
  5. Go live. The test postcard is in your Mailr dashboard, moving through every status in about 8 minutes, free. Add funds and set MAILR_API_KEY to your mlr_live_ key; every new lead from then on gets a printed piece.

The endpoint, or a Zap

// Receives Perspective's New Lead webhook and mails a postcard through Mailr.
// Secrets: MAILR_API_KEY, HOOK_TOKEN (a long random string, also the last part of the webhook URL).
export interface Env { MAILR_API_KEY: string; HOOK_TOKEN: string }

// Your design: start from a template's front.html and back.html in mailr.dev/downloads/mailr-kit.zip.
const FRONT = "<html>…your 6x9 front.html with {{first_name}}…</html>";
const BACK = "<html>…your 6x9 back.html…</html>";

// Perspective identifiers for each field. "state" is the custom text field you added.
const FIELDS = { name: "name", first: "firstName", last: "lastName", street: "address.street", city: "address.city", zip: "address.postalCode", state: "state" };

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    // Perspective's webhook docs describe no signature, so the URL itself carries a secret.
    if (req.method !== "POST" || new URL(req.url).pathname !== "/perspective/" + env.HOOK_TOKEN) {
      return new Response("not found", { status: 404 });
    }
    const lead: any = await req.json(); // { id, funnelName, meta, profile }

    // Each answer arrives as { value, title } under its identifier.
    const field = (id: string): string => {
      const p = lead.profile ?? {};
      const entry = p[id] ?? id.split(".").reduce((o: any, k) => o?.[k], p);
      return String(entry?.value ?? "").trim();
    };

    const zip = field(FIELDS.zip);
    const state = stateCode(field(FIELDS.state));
    if (!field(FIELDS.street) || !state || !/^\d{5}(-?\d{4})?$/.test(zip)) {
      console.log("Perspective lead without a US address", lead.id, lead.funnelName);
      return new Response("no US address, skipped");
    }
    const first = field(FIELDS.first) || field(FIELDS.name).split(" ")[0];
    const name = field(FIELDS.name) || (first + " " + field(FIELDS.last)).trim();

    const res = await fetch("https://api.mailr.dev/v1/postcards", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + env.MAILR_API_KEY,
        "Content-Type": "application/json",
        "Idempotency-Key": "perspective-lead-" + lead.id, // the contact id: one piece per lead
      },
      body: JSON.stringify({
        size: "6x9",
        front: FRONT,
        back: BACK,
        to: { name: name.slice(0, 40), line1: field(FIELDS.street), city: field(FIELDS.city), state, zip },
        merge: { first_name: first.slice(0, 14) },
        description: ("Perspective lead, " + lead.funnelName).slice(0, 255),
      }),
    });
    if (res.ok) return new Response("mailed");
    const err: any = await res.json().catch(() => ({}));
    console.log("Mailr", res.status, lead.id, err.error?.message);
    // A bad address won't fix itself: answer 200 and keep the log. Ask for a retry only when one can work.
    return new Response("not mailed", { status: res.status >= 500 || res.status === 402 || res.status === 409 ? 500 : 200 });
  },
};

const STATES = "AL Alabama,AK Alaska,AZ Arizona,AR Arkansas,CA California,CO Colorado,CT Connecticut,DE Delaware,DC District of Columbia,FL Florida,GA Georgia,HI Hawaii,ID Idaho,IL Illinois,IN Indiana,IA Iowa,KS Kansas,KY Kentucky,LA Louisiana,ME Maine,MD Maryland,MA Massachusetts,MI Michigan,MN Minnesota,MS Mississippi,MO Missouri,MT Montana,NE Nebraska,NV Nevada,NH New Hampshire,NJ New Jersey,NM New Mexico,NY New York,NC North Carolina,ND North Dakota,OH Ohio,OK Oklahoma,OR Oregon,PA Pennsylvania,RI Rhode Island,SC South Carolina,SD South Dakota,TN Tennessee,TX Texas,UT Utah,VT Vermont,VA Virginia,WA Washington,WV West Virginia,WI Wisconsin,WY Wyoming";
const BY_NAME = new Map(STATES.split(",").map((s) => [s.slice(3).toLowerCase(), s.slice(0, 2)]));

// A free-text state field: "Arizona", "az" and "AZ" all become "AZ".
function stateCode(input: string): string {
  const s = input.trim().replace(/\.$/, "");
  if (/^[A-Za-z]{2}$/.test(s)) return s.toUpperCase();
  return BY_NAME.get(s.toLowerCase()) ?? "";
}
  • The New Lead webhook sends a JSON object with id (the contact id), funnelName, meta (createdAt, convertedAt, completedAt and more) and profile, where each answer is a value and a title under its identifier, such as address.city. Log one real payload before you rely on the shape.
  • Perspective's webhook article doesn't describe a signing secret, extra headers or a retry policy. The Worker checks a secret in the URL path, answers 404 to anything else, and uses the contact id as the Idempotency-Key, so a repeated delivery within 24 hours returns the first postcard instead of printing a second.
  • Perspective's address fields are Street, City, Country and ZIP Code, with no state. Without the custom state field, US leads can't be mailed. Google address autocomplete for those fields is on the Advanced (legacy) or Expand plan, or with the Premium Block Suite.
  • Mailr mails to US addresses only. Leads from other countries are skipped and logged, not sent.
  • The Mailr key lives in the Worker's secrets or in the Zap, never in the funnel's custom code or tracking scripts, which run in the visitor's browser.

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.

Questions

A postcard per lead, or one batch a day?

Per lead for the funnel: each lead is one request, a bad address fails on its own, and the piece is created the moment the lead comes in. Use POST /v1/batches (up to 1,000 recipients per request, all checked before anything prints) for campaigns to leads you already have, such as everyone from last month who didn't book.

Can we mail the leads already in Perspective?

Yes. Perspective's API (from the Scale plan, with an x-perspective-api-key header and the crm:read scope) lists a funnel's contacts at GET /v1/funnels/{funnelId}/contacts. Map them the same way and send them to POST /v1/batches, building each batch's Idempotency-Key from its first and last contact id.

Can we do this without hosting anything?

Yes. Zapier's Perspective app has a New Lead via Funnel trigger; add the Code by Zapier step from the second tab. Make has a verified Perspective app with Watch for New Leads, followed by an HTTP module that sends the same request with the same headers. The key then lives in the Zap or scenario.

What if the same person goes through two funnels?

Perspective's API lists contacts per funnel, so they arrive as two contacts with two ids, and the idempotency key alone won't stop a second piece. If that matters, keep a record of mailed emails (Cloudflare KV, for example) and check it before sending.

How do we see what was delivered?

Every piece is in the Mailr dashboard with its status. Mailr doesn't send webhooks yet, so poll GET /v1/postcards/{id} if you want statuses back in your CRM.

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.
PERSPECTIVE

Mail from Perspective 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

Download the template kit?

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

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