Send events

POST /api/v1/events is the primary way to drive Mailr. Your CRM or automation stack pushes an event when something happens — a job completes, a deal is won, a contact is created — and Mailr matches it against the automations you’ve bound and, when one fires, enqueues a per-recipient Street View postcard campaign. Required scope: events:write · Rate limit: 120 events / minute / org · Max body: 256 KB

The trigger-binding concept

There is no “connect” flow for the developer API — your key is the credential. The first valid event lazily creates a hidden custom connection for your org. What turns an event into a postcard is a binding you create in the app:

Send at least one live event

Live events are sampled — Mailr keeps a rolling sample of ~25 recent events per event_type so your event types show up in the app’s binding picker. Dry-run events write nothing and are not sampled.

Create an automation and bind it

In the app, set an automation’s trigger to Custom API and bind it to an event_type and optionally an object_type. A binding with no object type accepts any; a binding that pins one only fires for that type.

Events now fire that automation

Each matching event runs the same trigger core the 14 native CRM integrations use: CRM filters → address check → idempotent enqueue → (for contacts) attribution.

matched_automations in the response counts bindings whose event_type/object_type matched — not bindings that actually mailed. Always read outcomes[].reason for what really happened.

The envelope

string

required

Your event name as noun.verb, lowercase letters/digits/underscores, ≤64 chars (e.g. job.completed). Bound in the app as custom.<event_type>.

string

required

One of job, deal, contact. A contact event that carries an address plus an email or phone is also run through indirect attribution.

string

required

Your idempotency key for this event, ≤255 chars. Replaying the same value is absorbed per bound automation.

string (ISO-8601)

When the event happened. Optional. May lead the server clock by at most 24 hours.

boolean

default:"false"

Validate and report outcomes without writing anything. See Dry run.

string

required

Your record’s id in your system, ≤128 chars.

object

A flat map of string → string, at most 100 keys. Values must be strings (numbers/booleans/nulls are rejected, not coerced) of ≤2000 chars. Keys are lowercase snake_case, ≤64 chars, starting with a letter, and must be a reserved key or cf_-prefixed.

Reserved vs custom properties

These keys have defined meaning to Mailr:

Key	Meaning
`street`	Street line. Required (with `city` or `zip`) to mail.
`city`, `state`, `zip`	Locality. `street` + (`city` or `zip`) is the minimum mailable address.
`client_name`	Recipient name printed on the card.
`client_email`, `client_phone`	Used for contact attribution.
`amount`	Deal/job value (as a string).
`status`	Stage/status, matchable in automation filters.
`mailr_lead_id`	Echo-loop guard — see below.

Every other property MUST be prefixed cf_. This is deliberate: a typo in a reserved key (zipcode, clientemail) is rejected at the edge with a 422 rather than silently producing a wrongly-addressed postcard.

A campaign needs street and at least one of city / zip. Anything less is reported per automation as reason: "no_address" and nothing mails.

The mailing address is composed from street, city, state and zip. The combined value must be at most 500 characters — a longer composed address is rejected with a 422.

Example

curl -X POST https://app.getmailr.com/api/v1/events \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "job.completed",
    "object_type": "job",
    "dedup_id": "job-8842-completed",
    "occurred_at": "2026-08-19T15:04:00Z",
    "record": {
      "id": "8842",
      "properties": {
        "street": "3134 River Valley Dr",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "client_name": "Dana Reyes",
        "client_email": "dana.reyes@example.com",
        "amount": "6400.00",
        "status": "completed",
        "cf_trade": "roofing"
      }
    }
  }'

const res = await fetch("https://app.getmailr.com/api/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_type: "job.completed",
    object_type: "job",
    dedup_id: "job-8842-completed",
    occurred_at: "2026-08-19T15:04:00Z",
    record: {
      id: "8842",
      properties: {
        street: "3134 River Valley Dr",
        city: "Austin",
        state: "TX",
        zip: "78701",
        client_name: "Dana Reyes",
        client_email: "dana.reyes@example.com",
        amount: "6400.00",
        status: "completed",
        cf_trade: "roofing",
      },
    },
  }),
});

if (!res.ok) throw new Error(`Mailr API returned ${res.status}`);
console.log(await res.json()); // read outcomes[].reason

import os
import requests

payload = {
    "event_type": "job.completed",
    "object_type": "job",
    "dedup_id": "job-8842-completed",
    "occurred_at": "2026-08-19T15:04:00Z",
    "record": {
        "id": "8842",
        "properties": {
            "street": "3134 River Valley Dr",
            "city": "Austin",
            "state": "TX",
            "zip": "78701",
            "client_name": "Dana Reyes",
            "client_email": "dana.reyes@example.com",
            "amount": "6400.00",
            "status": "completed",
            "cf_trade": "roofing",
        },
    },
}

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

res.raise_for_status()
print(res.json())  # read outcomes[].reason

<?php
$payload = [
    "event_type" => "job.completed",
    "object_type" => "job",
    "dedup_id" => "job-8842-completed",
    "occurred_at" => "2026-08-19T15:04:00Z",
    "record" => [
        "id" => "8842",
        "properties" => [
            "street" => "3134 River Valley Dr",
            "city" => "Austin",
            "state" => "TX",
            "zip" => "78701",
            "client_name" => "Dana Reyes",
            "client_email" => "dana.reyes@example.com",
            "amount" => "6400.00",
            "status" => "completed",
            "cf_trade" => "roofing",
        ],
    ],
];

$ch = curl_init("https://app.getmailr.com/api/v1/events");
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 !== 202) {
    throw new RuntimeException("Mailr API returned $status: $body");
}
print_r(json_decode($body, true)); // read outcomes[].reason

202 Accepted

{
  "received": true,
  "duplicate": false,
  "matched_automations": 1,
  "outcomes": [
    {
      "automation_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Post-job reactivation",
      "matched": true,
      "reason": "queued"
    }
  ]
}

Outcomes

Each candidate binding reports one reason:

reason

A campaign was enqueued (on a dry run, would be enqueued). matched: true.

reason

The automation’s CRM filters excluded this record.

reason

No street plus city/zip.

reason

This dedup_id already enqueued for this automation. When every candidate is a duplicate, the top-level duplicate is true.

reason

mailr_lead_id matched one of your own leads — see below.

reason

The enqueue itself threw. Logged to your webhook log; not silently reported as queued.

Loop guard

If a Mailr-delivered lead lands in your CRM and your automation fires an event straight back at us, you’d start a campaign off an address Mailr itself just sourced — forever. To prevent that, the outbound lead delivery carries a mailr_lead_id. Echo it back in record.properties.mailr_lead_id on any event derived from a Mailr lead:

{ "record": { "properties": { "mailr_lead_id": "c1d2e3f4-0000-0000-0000-000000000020", "...": "..." } } }

When Mailr recognizes one of your own lead ids, every candidate reports reason: "loop_guard" and nothing mails. A mailr_lead_id that is not one of your leads is ignored and the event takes the normal path.

Dry run

dry_run: true runs the full pipeline — binding match, CRM filters, address check, dedup lookup — and returns exactly the outcomes a live call would, but writes nothing: no connection upsert, no sample, no enqueue, no log. Use it to validate a binding before mailing. The response echoes dry_run: true so a log reader can tell a rehearsal from a live call.

A dry run still consumes one unit of the 120/min quota — it does the same work as a live call.

Status codes

Status	`error`	Meaning
`202`	—	Accepted (read `outcomes`).
`400`	`invalid_json` / `invalid_payload`	Unreadable body or invalid JSON.
`401`	`unauthorized`	Missing/invalid/revoked/expired key.
`403`	`unauthorized`	No org resolved, or missing `events:write`.
`413`	`payload_too_large`	Body over 256 KB.
`422`	`invalid_payload`	Envelope validation failed; `detail` names the field.
`429`	`rate_limited`	Over 120/min. `Retry-After: 60`.
`503`	`automations_disabled`	Platform kill switch. `Retry-After: 300` — retry, don’t drop.
`500`	`internal_error`	Unexpected server error.

Developer API

Endpoints

The trigger-binding concept

The envelope

Reserved vs custom properties

Example

Outcomes

Loop guard

Dry run

Status codes

​The trigger-binding concept

​The envelope

​Reserved vs custom properties

​Example

​Outcomes

​Loop guard

​Dry run

​Status codes

The trigger-binding concept

The envelope

Reserved vs custom properties

Example

Outcomes

Loop guard

Dry run

Status codes