Skip to main content
The Mailr Developer API lets a contractor’s own CRM or automation stack drive Mailr directly — no vendor polling, no Zapier in the middle. There are four things you can do:

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:
The key alone identifies the tenant. You never pass an 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 accountAPI 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.
Failed auth never reveals whether a given key exists. 401 covers missing/invalid/revoked/expired keys; 403 covers a key that resolves to no organization or is missing a required scope.

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

There is no reconciliation sweep. Mailr never reaches back into your CRM to pull anything it missed — the caller is the sync. If a push fails, or you suspect a gap, replay your events. Idempotency makes replays free, so replaying a whole window is the correct recovery, not the exception.

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.