Mail API reference

Mail API · Deliverability

get/v1/workspaces/{workspace_id}/deliverabilityAuth

Deliverability verdict for the workspace over a lookback window. `unconfirmed` means mail was handed off and nothing came back either way — it is not a synonym for healthy.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Query parameters

window_daysnumber

Lookback in days, 1–90. Defaults to 14 — the length of the outage in tasks/mail-api/002.

Response · 200

verdict*object

Overall verdict. `unconfirmed` is NOT a synonym for healthy: it means mail was handed off and nothing came back in either direction, which is the shape a blackholed sender makes. `healthy` requires positive recipient-side evidence.

Example: "unconfirmed"

window_days*number

Lookback used, in days.

Example: 14

left_queue*number

Messages handed off for delivery in the window.

Example: 80

queued*number

Messages still waiting to be handed off.

Example: 0

confirmed*number

Messages with recipient-side evidence of arrival. Zero across the estate today — nothing emits that evidence yet, and reporting zero is the honest answer rather than assuming success.

Example: 0

negative*number

bounced + complained + failed + deferred.

Example: 7

deferred*number

Messages currently deferred.

Example: 235

bounced*number

Messages hard-bounced.

Example: 7

negative_rate*number

negative / left_queue.

Example: 0.0875

confirmed_rate*number

confirmed / left_queue.

Example: 0

block_signals*array

Diagnostics that matched a known reputation-block signature.

summary*string

One actionable sentence.

Example: "80 message(s) were handed off and none has been confirmed as arriving."

domains*array

Each sending domain with its DMARC grade. Gmail and Yahoo require DMARC from bulk senders, so a domain with `dmarc.location = none` is a deliverability risk regardless of the verdict.

Example

Request

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/deliverability
Authorization: Bearer YOUR_TOKEN

Response

{
  "verdict": "unconfirmed",
  "window_days": 14,
  "left_queue": 80,
  "queued": 0,
  "confirmed": 0,
  "negative": 7,
  "deferred": 235,
  "bounced": 7,
  "negative_rate": 0.0875,
  "confirmed_rate": 0,
  "block_signals": [
    {
      "detail": "554 5.7.1 Blocked using Proofpoint Dynamic Reputation",
      "count": 37
    }
  ],
  "summary": "80 message(s) were handed off and none has been confirmed as arriving.",
  "domains": [
    {
      "fqdn": "mail.example.com",
      "status": {},
      "dmarc": {}
    }
  ]
}