MX Health
developer/v1/dns/mx-healthPerforms end-to-end health checks on mail servers — DNS resolution AND a real SMTP handshake. Resolves each MX host to A and AAAA records, then opens a TCP probe to the mail server, reads the SMTP greeting, sends EHLO, and verifies opportunistic TLS works (RFC 8314). Probes the Submission port (587, RFC 6409) with STARTTLS and the SMTPS port (465) with implicit TLS — both expose the same TLS configuration that the MX uses for relay traffic. Detects Null MX (RFC 7505) domains and surfaces classification (status, capabilities, TLS state) per MX.
What It Does
For each MX, resolves the hostname to A and AAAA records, then performs a real SMTP probe over TCP. The probe opens a connection, reads the SMTP 220 greeting, sends EHLO, parses advertised capabilities, performs STARTTLS (port 587) or implicit TLS (port 465), and returns per-MX status: greeting line, capability list, TLS handshake outcome. Aggregates whether any MX is healthy (`any_smtp_ok`) and whether every probed MX successfully negotiated TLS (`all_tls_ok`). Probing is opt-out via `?smtp_probe=false` for callers who only want the DNS-level checks.
Why It's Useful
A name that says "Health" should health-check the actual mail service, not just resolve names. Reading the SMTP greeting and verifying the TLS handshake answers the questions email administrators actually have: is the server up? does it offer opportunistic TLS as RFC 8314 requires? are the cipher and certificate negotiation healthy? Failed handshakes and missing STARTTLS surface as actionable issues, not buried network noise. Complements SPF, DKIM, DMARC, and MTA-STS by testing the live mail-transport layer.
Use Cases
Pre-Campaign TLS Posture Check
Before launching a major campaign, verify that recipient mail servers accept connections AND offer opportunistic TLS per RFC 8314. The live SMTP probe sends EHLO, parses advertised capabilities, and confirms STARTTLS or SMTPS works — the exact controls Gmail and Microsoft 365 require under their bulk-sender policies.
Catch recipients whose MX is up but TLS is broken (expired cert, missing STARTTLS) — the failure mode that turns deliverable mail into spam-folder mail.
Vendor Email Security Assessment
Evaluate a vendor's mail infrastructure during onboarding. The probe surfaces whether their MX accepts TLS submissions, advertises proper capabilities (SIZE, 8BITMIME, AUTH), and completes the handshake cleanly. Combined with SPF, DKIM, and DMARC checks, gives a complete email-stack posture in two API calls.
Identify partners running outdated or misconfigured mail servers before signing contracts that depend on reliable email exchange.
Continuous TLS-Posture Monitoring
Schedule mx-health probes against business-critical partner domains. Alert on `all_tls_ok` regressions — the most common cause is a silently-expired TLS cert on the MX, which degrades from "works" to "delivered as cleartext" without any visible error.
Detect TLS regressions on inbound mail paths within minutes, not after the certificate-monitoring tool finally surfaces the renewal.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Required | The domain to check mail server health forExample: example.com |
smtp_probe | string | Optional | Set to "false" to skip the live SMTP probe and return only the DNS-level checks. Defaults to "true".Example: true |
Response Fields
| Field | Type | Description |
|---|---|---|
domain | string | The queried domain |
mx_records | array | Per-MX detail: priority, host, ips, reachable, error, plus an `smtp_probe` object with port, probe_kind ("submission" | "smtps"), status, tcp_connected, greeting, supports_starttls, tls_negotiated, capabilities[], duration_ms |
has_valid_mx | boolean | Whether domain has at least one reachable MX server (resolves to A/AAAA records) |
all_reachable | boolean | Whether all MX servers resolve to at least one IP address |
smtp_probe_enabled | boolean | Whether the live SMTP probe ran (false when smtp_probe=false was passed) |
any_smtp_ok | boolean | True if at least one MX completed a successful SMTP handshake with TLS |
all_tls_ok | boolean | True iff every probed MX successfully negotiated TLS (via STARTTLS on 587 or implicit on 465); null when no probes were run |
issues | array | Configuration-level findings, e.g., "MX host X does not advertise STARTTLS — mail submission is sent in cleartext (RFC 8314)" or "EHLO handshake failed at host Y" |
count | number | Number of MX records found |
Code Examples
curl "https://api.edgedns.dev/v1/dns/mx-health" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "domain=example.com"const response = await fetch(
'https://api.edgedns.dev/v1/dns/mx-health?domain=example.com',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(data);import requests
response = requests.get(
'https://api.edgedns.dev/v1/dns/mx-health',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'domain': 'example.com'
}
)
data = response.json()
print(data)Read the full MX Health guide
Why it matters, real-world use cases, parameters, response fields, and how to call it from Claude, ChatGPT, or Gemini via MCP.
Read the guide →Related Endpoints
External References
Learn more about the standards and protocols behind this endpoint.