Skip to Content
SendlySendly
API ReferenceDeliverability

Diagnose why mail from a domain is not arriving

GET
/api/v1/deliverability/diagnose

Reads the sending domain's DNS identity, the project's delivery outcomes over the last window_days, and — when an address is given — that recipient's suppression state, then publishes findings: what is actually wrong, worst first, each with a stable code and the fix. Branch on code, never on the prose.

Everything here is read from data the platform already holds. The DNS statuses are the cached results of the verification refresh job, NOT a live lookup — identity.last_checked_at says when they were filled, and a domain that has never been checked reports nulls with a dns_never_checked finding rather than failures.

recent_delivery is PROJECT-WIDE, not per-domain, because an email row records no sending domain; the field says so in its own scope. Rates are suppressed as meaningless below 20 sends in the window.

Requires the deliverability:read scope — Check why mail from one of your domains is not arriving.

headerAuthorizationBearer <API Key>

API key authentication. Use a sk_* (FULL) or pk_* (SENDING_ONLY) key as the bearer token. Public keys (pk_*) are restricted to the email-send endpoints and the self-serve list subscribe/unsubscribe pair; every other endpoint — event tracking included — answers 403 for them. In scope terms (used by /api/v1/* operations): FULL keys hold every scope; SENDING_ONLY keys hold only emails:send.

domain*string

A sending domain in this project, e.g. example.com.

Length3 <= length <= 253
address?string

Optionally, one RECIPIENT address to check as well. Adds its suppression state — the single most common reason a specific person stops receiving mail while everyone else still does.

Formatemail
window_days?integer

How far back the delivery counters look. 1–30 days; defaults to 7.

Range1 <= value <= 30

Response Body

The diagnosis, with findings

application/json
  1. response

A composed answer to why mail from one domain may not be arriving: its DNS identity, the project's recent delivery outcomes, one address's suppression state, and the findings drawn from them.

domain*string
address*string|null
checked_at*string
Formatdate-time
identity*

The sending identity's DNS health, as last refreshed.

suppression*|

Null unless the request named an address.

recent_delivery*

Delivery outcomes over the requested window.

findings*array<>

What is wrong, worst first. An empty array means nothing here explains a delivery problem.

Example Request
curl -X GET 'https://api.sendly.now/api/v1/deliverability/diagnose?domain=string'
Example Response
{  "domain": "string",  "address": "string",  "checked_at": "2019-08-24T14:15:22Z",  "identity": {    "registered": true,    "verified": true,    "dkim_status": "NOT_CHECKED",    "spf_status": "NOT_CHECKED",    "dmarc_status": "NOT_CHECKED",    "mx_status": "NOT_CHECKED",    "mail_from_domain": "string",    "mail_from_domain_status": "string",    "last_checked_at": "2019-08-24T14:15:22Z"  },  "suppression": {    "suppressed": true,    "reason": "HARD_BOUNCE",    "source": "SES_WEBHOOK",    "suppressed_at": "2019-08-24T14:15:22Z"  },  "recent_delivery": {    "window_days": 0,    "scope": "project",    "sent": 0,    "delivered": 0,    "bounced": 0,    "complained": 0,    "failed": 0,    "bounce_rate": 0,    "complaint_rate": 0  },  "findings": [    {      "code": "string",      "severity": "blocking",      "summary": "string",      "remedy": "string"    }  ]}