Diagnose why mail from a domain is not arriving
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.
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.
In: header
Query Parameters
A sending domain in this project, e.g. example.com.
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.
How far back the delivery counters look. 1–30 days; defaults to 7.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/deliverability/diagnose?domain=string"{
"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"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}