Send events
Push a
job.completed / deal.won / contact event; Mailr matches it against your automations and mails
a per-recipient Street View postcard.Receive leads
Subscribe an endpoint to receive landing-page leads back, HMAC-signed.
Attribution & revenue
Report won deals and synced leads so revenue attributes to the campaign that mailed the address.
Import past jobs
Stage a batch of completed jobs for a reactivation campaign.
The OpenAPI spec behind the Endpoints section of this reference is the source of truth for every path,
field, status code and header. These pages explain the concepts; the spec pins the shapes.
Base URL
All paths are relative to:Versioning
The public API is versioned under/api/v1/*, and every endpoint in these docs uses that prefix. The
Mailr Zapier app targets /api/v1/*; build new integrations against the same prefix.
Authentication
Every endpoint authenticates with an organization-scoped API key presented as a bearer token:org_id, connection id, or batch id — anything you
could name is derived from the key. Create a key in the Mailr app: click your workspace name (bottom-left) → Manage account → API keys. Only the workspace Owner can create or revoke keys.
Verify a key against your org with GET /api/v1/me:
Response
Scopes
Keys may declare scopes. The policy in v1 is deliberately forgiving:- A key that declares no scopes is treated as unrestricted and passes every check.
- A key that declares any scopes must include the scope an operation requires, or the call returns
403.
scope
Required by
POST /api/v1/events.scope
Required by
POST /api/v1/import/jobs.scope
Required by the lead, attribution, customer, trigger, subscribe,
/api/v1/me, and /api/v1/automation/list
endpoints.Idempotency
Every write is idempotent on a caller-supplied key, so retries and replays are safe:
The response tells you when a replay was absorbed:
duplicate: true, idempotent: true, or an outcome with
reason: "duplicate".
Delivery cadence — replay, don’t reconcile
What’s not in this API
The dashboard’s own browser-authenticated endpoints (for example/api/integrations/custom/event-config) are session-authed and are not part of this bearer-key API. Only
the ak_-key endpoints documented here are public.
Next steps
Send your first event
The envelope, trigger bindings, outcomes, and dry run.
Go-live checklist
Eight things to confirm before production traffic.