Ingest a CRM/automation event
Push one event from your CRM/automation stack. Mailr matches it against
the automations bound to your custom connection and, when a binding
fires, enqueues a per-recipient postcard campaign through the same core
the native CRM syncs use.
The connection is created lazily on the first valid event — the key is
the credential, so there is no connect flow. Bind an automation to an
event_type + object_type in the app (Automations → trigger →
“Custom API”); Mailr keeps a rolling sample of recent events per type to
populate the binding picker.
Reserved vs custom properties. The reserved keys (street, city,
state, zip, client_name, client_email, client_phone, amount,
status, mailr_lead_id) have defined meaning. Every other property
MUST be prefixed cf_ — a typo in a reserved key (zipcode,
clientemail) is rejected at the edge rather than silently producing a
wrongly-addressed postcard.
Address requirement. A campaign needs street AND at least one of
city/zip; anything less is reported per automation as
reason: "no_address" (no postcard). The composed mailing address
(street + city + state + zip, combined) must be at most 500
characters, or the event is rejected with a 422.
Loop guard. If a Mailr-delivered lead landed in your CRM and your
automation fires an event back at us, stamp the lead id in
mailr_lead_id; matching is skipped and each candidate reports
reason: "loop_guard". 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 binding match, filter, address
and dedup checks and returns exactly the outcomes a live call would — but
writes nothing (no connection upsert, no sample, no enqueue, no log). A
dry run still costs one unit of rate-limit quota.
Authorizations
Organization-scoped Mailr API key. Header: Authorization: Bearer ak_….
Body
Your event name as noun.verb, lowercase, ≤64 chars. Bound in the app as custom.<event_type>.
64^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$"job.completed"
What kind of record this event is about. A contact event with an address and email/phone is also run through indirect attribution.
job, deal, contact Your idempotency key for this event. Replaying the same value is absorbed per bound automation.
255"job-8842-completed"
When the event happened (ISO-8601). Optional. May lead the server clock by at most 24h.
Validate and report outcomes without writing anything. Still consumes rate-limit quota.
Response
Accepted. The event was validated and processed. matched_automations
counts bindings whose event_type/object_type matched — not bindings
that actually mailed; read outcomes[].reason for the per-automation
result. duplicate is true only when every candidate hit the campaign
queue's dedup.
True only when there was at least one candidate binding and every one hit the campaign-queue dedup.
Count of bindings whose event_type/object_type matched — not the count that mailed.
Present and true only when the request set dry_run.