08 · MailMarco API

Deliverability

Four different mechanisms can refuse a send. Each has its own status code, and each tells you something different about what to fix.

Suppressions#

A suppression blocks an address from receiving anything from your organization. The send path checks every recipient — to, cc and bcc — before the message is written, and one suppressed recipient rejects the entire message with 400 recipient suppressed: <address>. There is no partial send.

Suppressions accumulate from two directions: you add them, and the bounce pipeline adds them for you when a hard bounce or a complaint comes back.

curl -X POST https://api.mailmarco.com/v1/suppressions \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"address":"[email protected]","scope":"tenant","reason":"bounce"}'

{
  "id": "8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
  "address": "[email protected]",
  "scope": "tenant",
  "reason": "bounce",
  "createdAt": "2026-07-29T10:15:00.000Z"
}

{ "deleted": true }

Bounces#

A bounce is the receiving server refusing the message. MailMarco attributes bounces through a signed return-path address, so attribution comes from the envelope token rather than from parsing the bounce body.

[
  {
    "id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
    "messageId": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "address": "[email protected]",
    "type": "hard",
    "code": "550",
    "diagnostic": "550 5.1.1 <[email protected]>: Recipient address rejected",
    "at": "2026-07-29T09:24:03.000Z"
  }
]

Complaints#

A complaint is a recipient pressing “this is spam”. It arrives through the provider's feedback loop, not through SMTP, so it is a different signal from a bounce and a far more serious one — the tolerated complaint rate is roughly forty times lower than the tolerated bounce rate.

[
  {
    "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819",
    "messageId": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "address": "[email protected]",
    "source": "feedback-loop",
    "at": "2026-07-29T11:02:41.000Z"
  }
]

Your reputation#

/v1/reputation is your organization's own view of its sending health. It is session-authenticated, and there is deliberately no organization id on any route — the org comes from the token.

{ "reports": [ /* … */ ], "sources": [ /* … */ ] }

Plan limits (402)#

Sends are metered against the plan attached to your subscription, per calendar month (YYYY-MM). Exceeding the allowance answers 402 Payment Required:

{
  "error": "plan_limit_exceeded",
  "metric": "emails_sent",
  "limit": 50000,
  "message": "Plan limit reached for emails_sent"
}

• The counter is incremented in the same transaction that writes the message, and only after the message row is confirmed. A rejected or idempotently-deduped send consumes nothing.
• The check is an atomic conditional increment, so concurrent sends cannot both slip past the cap.
• An organization with no subscription is unmetered: no limit is applied and no counter is written. A subscribed organization on a plan that does not cap emails_sent is metered for billing but never rejected.
• Sandbox sends take the same metering path, so they count.

Warm-up caps (429)#

A new organization can be placed on a warm-up schedule with a daily cap that grows over time. Once today's cap is reached, sends are refused until the next day:

{
  "error": "warmup_cap_reached",
  "message": "warm-up daily send cap reached"
}

The cap is checked before anything is written, and the counter is incremented inside the message transaction, so a rejected send never consumes a slot. An organization with no warm-up configured is unrestricted by this rule.

What pauses an organization#

A rule engine evaluates a rolling window of your real events and can change the organization's status. A window with fewer than the minimum sample of sends produces no action at all — a couple of bounces on a handful of messages is noise.

Thresholds are per organization and can be adjusted by an operator. If both rules fire, the pause wins.

While suspended

{
  "error": "org_suspended",
  "message": "organization sending is paused"
}

Every send is refused, including sandbox sends and messages that were already scheduled — the paused state is re-checked when a scheduled message comes due, so scheduling ahead of a suspension does not evade it. Reads keep working. Reactivation is an operator action.

Endpoints#

Covered above: GET/POST /v1/suppressions, DELETE /v1/suppressions/:id, GET /v1/bounces, GET /v1/complaints, GET /v1/reputation, GET /v1/reputation/timeseries, GET /v1/reputation/dmarc.

Threshold configuration and tenant suspension live on the operator surface (/v1/admin/deliverability/:orgId/thresholds and /v1/admin/tenants/:id/{suspend,reactivate,limit}) and require a platform-admin token; they are not part of the customer API.