Attribution & revenue

Attribution closes the loop: you tell Mailr about deals and leads happening in your CRM, and Mailr matches each address back to the campaign that mailed it (geo-first, org-scoped, within a 180-day window). Two endpoints, both scoped webhooks:inbound, both rate-limited to 60 requests / minute / org.

The org is always taken from the API key, never from the request body — an org_id in the body is ignored. Both endpoints tolerate HubSpot/Zapier field shapes: most fields can be sent flat or nested under a properties object.

Report a won deal

POST /api/v1/conversions attributes revenue. Mailr resolves the deal’s address to a mailed campaign and upserts an idempotent conversion; the address is also recorded as an existing customer regardless of whether revenue attributes. Unmatched deals are discarded.

curl -X POST https://app.getmailr.com/api/v1/conversions \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "3134 River Valley Dr, Austin, TX 78701",
    "deal_id": "deal-9931",
    "deal_amount": "6400.00",
    "deal_stage": "closed_won",
    "deal_name": "Reyes roof replacement",
    "contact_first_name": "Dana",
    "contact_last_name": "Reyes",
    "contact_email": "dana.reyes@example.com",
    "deal_date": "2026-08-19"
  }'

const res = await fetch("https://app.getmailr.com/api/v1/conversions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    address: "3134 River Valley Dr, Austin, TX 78701",
    deal_id: "deal-9931",
    deal_amount: "6400.00",
    deal_stage: "closed_won",
    deal_name: "Reyes roof replacement",
    contact_first_name: "Dana",
    contact_last_name: "Reyes",
    contact_email: "dana.reyes@example.com",
    deal_date: "2026-08-19",
  }),
});

if (!res.ok) throw new Error(`Mailr API returned ${res.status}`);
console.log(await res.json()); // { matched: true, ... } or { matched: false }

import os
import requests

payload = {
    "address": "3134 River Valley Dr, Austin, TX 78701",
    "deal_id": "deal-9931",
    "deal_amount": "6400.00",
    "deal_stage": "closed_won",
    "deal_name": "Reyes roof replacement",
    "contact_first_name": "Dana",
    "contact_last_name": "Reyes",
    "contact_email": "dana.reyes@example.com",
    "deal_date": "2026-08-19",
}

res = requests.post(
    "https://app.getmailr.com/api/v1/conversions",
    headers={"Authorization": "Bearer " + os.environ["MAILR_API_KEY"]},
    json=payload,
)

res.raise_for_status()
print(res.json())  # {'matched': True, ...} or {'matched': False}

<?php
$payload = [
    "address" => "3134 River Valley Dr, Austin, TX 78701",
    "deal_id" => "deal-9931",
    "deal_amount" => "6400.00",
    "deal_stage" => "closed_won",
    "deal_name" => "Reyes roof replacement",
    "contact_first_name" => "Dana",
    "contact_last_name" => "Reyes",
    "contact_email" => "dana.reyes@example.com",
    "deal_date" => "2026-08-19",
];

$ch = curl_init("https://app.getmailr.com/api/v1/conversions");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("MAILR_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Mailr API returned $status: $body");
}
print_r(json_decode($body, true)); // ['matched' => true, ...] or ['matched' => false]

200 OK — matched

{
  "matched": true,
  "attribution_type": "direct",
  "campaign_id": "aa11bb22-0000-0000-0000-0000000000cc",
  "match_method": "geo",
  "match_confidence": "high",
  "conversion_id": "d4e5f6a7-0000-0000-0000-000000000030"
}

200 OK — unmatched

{ "matched": false }

string

required

The deal’s service address. Also accepted as properties.address / deal_address / install_address.

string

Your deal id. Drives idempotency. Also properties.hs_object_id / objectId.

string | number

Deal value. A number or numeric string.

string (ISO-8601)

Close date. Drives last-touch attribution within the 180-day window.

string

Optional Mailr campaign id for an exact, address-independent attribution.

string

Optional deal/contact details, stored with the conversion.

Sync a new lead (indirect)

POST /api/v1/tracking/lead records a lead your CRM captured elsewhere as an indirect lead against the mailed campaign (source = crm_sync). Unmatched leads are discarded. Idempotency uses crm_record_id first, then a non-empty email or phone. Records with none of those identity fields stay distinct instead of sharing an empty email key. When a CRM record originated from Mailr, echo its mailr_lead_id; Mailr returns { "matched": false, "reason": "loop_guard" } without re-ingesting it. These leads are never delivered back outbound. If the address already has a direct landing-page lead, the sync collapses onto it and returns duplicate: true with attribution_type: "direct" — the existing lead is not downgraded.

curl -X POST https://app.getmailr.com/api/v1/tracking/lead \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "3134 River Valley Dr, Austin, TX 78701",
    "first_name": "Dana",
    "last_name": "Reyes",
    "email": "dana.reyes@example.com",
    "phone": "+15125550143",
    "crm_record_id": "crm-contact-4821",
    "created_at": "2026-08-19T15:04:00Z"
  }'

const res = await fetch("https://app.getmailr.com/api/v1/tracking/lead", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    address: "3134 River Valley Dr, Austin, TX 78701",
    first_name: "Dana",
    last_name: "Reyes",
    email: "dana.reyes@example.com",
    phone: "+15125550143",
    created_at: "2026-08-19T15:04:00Z",
  }),
});

if (!res.ok) throw new Error(`Mailr API returned ${res.status}`);
console.log(await res.json()); // { matched: true, duplicate: false, ... }

import os
import requests

payload = {
    "address": "3134 River Valley Dr, Austin, TX 78701",
    "first_name": "Dana",
    "last_name": "Reyes",
    "email": "dana.reyes@example.com",
    "phone": "+15125550143",
    "created_at": "2026-08-19T15:04:00Z",
}

res = requests.post(
    "https://app.getmailr.com/api/v1/tracking/lead",
    headers={"Authorization": "Bearer " + os.environ["MAILR_API_KEY"]},
    json=payload,
)

res.raise_for_status()
print(res.json())  # {'matched': True, 'duplicate': False, ...}

<?php
$payload = [
    "address" => "3134 River Valley Dr, Austin, TX 78701",
    "first_name" => "Dana",
    "last_name" => "Reyes",
    "email" => "dana.reyes@example.com",
    "phone" => "+15125550143",
    "created_at" => "2026-08-19T15:04:00Z",
];

$ch = curl_init("https://app.getmailr.com/api/v1/tracking/lead");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("MAILR_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Mailr API returned $status: $body");
}
print_r(json_decode($body, true)); // ['matched' => true, 'duplicate' => false, ...]

200 OK — matched

{
  "matched": true,
  "duplicate": false,
  "lead_id": "c1d2e3f4-0000-0000-0000-000000000020",
  "campaign_id": "aa11bb22-0000-0000-0000-0000000000cc",
  "attribution_type": "indirect"
}

200 OK — unmatched

{ "matched": false }

Trigger a specific automation directly

POST /api/v1/webhooks/trigger?id=<automationId> fires one named automation — the older mechanism the Zapier app and HubSpot workflows use. It’s still supported, but for new integrations prefer POST /api/v1/events: it binds by event type instead of hardcoding an automation id, and reports per-automation outcomes. Field extraction is highly tolerant of CRM/Zapier mappings; it’s idempotent on deal_id (a repeat short-circuits before geocoding), and a deal_won automation also attributes revenue as a side effect.

202 Accepted

{
  "success": true,
  "automation": "Post-job reactivation",
  "customer_added": true,
  "queued": true,
  "queue_id": "e5f6a7b8-0000-0000-0000-000000000040",
  "idempotent": false,
  "address": "3134 River Valley Dr, Austin, TX 78701, USA"
}

Discover automation ids with GET /api/v1/automation/list → { "automations": [{ id, name, enabled }] }.

A foreign automation id returns the same 404 as a missing one — a key can’t probe another org’s automation ids.

Registering existing customers

POST /api/v1/customers/webhook suppresses addresses from future mailings. Send a single { address, notes? } or a batch { addresses: [...] }; it upserts on the normalized address per org and returns { added, total }. A batch is capped at 1000 addresses — more is a 422. The endpoint is rate-limited to 60 requests / minute / org in its own bucket (separate from the two attribution endpoints above); over-limit responses are 429 with Retry-After: 60.

Developer API

Endpoints

Report a won deal

Sync a new lead (indirect)

Trigger a specific automation directly

Registering existing customers

​Report a won deal

​Sync a new lead (indirect)

​Trigger a specific automation directly

​Registering existing customers

Report a won deal

Sync a new lead (indirect)

Trigger a specific automation directly

Registering existing customers