{ "openapi": "3.1.0", "info": { "title": "TamingDNS API", "version": "1.0.0", "summary": "DNS and email-authentication checks: SPF, DKIM, DMARC, DNSSEC, DANE, MX, MTA-STS, TLS-RPT, BIMI, and raw email headers.", "description": "Read-only diagnostic checks for email deliverability and DNS. Every operation resolves live DNS (and, where the standard requires it, live HTTPS and X.509) and returns the canonical result envelope documented at https://tamingdns.com/developers.\n\nThe same checks are available to MCP clients over JSON-RPC 2.0 at https://tamingdns.com/mcp. Each operation carries `x-mcp-tool`, the name to call it by over JSON-RPC; `operationId` matches it except on the POST twin of a check that also answers GET. Note that `x-mcp-tool` is the name you INVOKE, while the `tool` member of the response envelope is the engine that answered — they differ for email-headers (`analyze_email_headers` invokes `check_email_headers`).\n\nNo authentication. Results are cached for 60 seconds per input.", "contact": { "name": "OSH.co.za", "url": "https://osh.co.za/contact-us/" }, "license": { "name": "Free to use", "url": "https://tamingdns.com/about" } }, "servers": [ { "url": "https://tamingdns.com", "description": "Production" } ], "externalDocs": { "description": "Developer documentation", "url": "https://tamingdns.com/developers" }, "tags": [ { "name": "checks", "description": "Read-only DNS and email-authentication checks." } ], "paths": { "/api/v1/spf": { "get": { "operationId": "check_spf", "x-mcp-tool": "check_spf", "summary": "Check the SPF record for a domain.", "description": "Check the SPF record for a domain. Returns the raw record, grade (A-F), the terminal `all` qualifier (resolved through redirect= chains), structured findings (NEAR_LOOKUP_LIMIT, LOOKUP_LIMIT_EXCEEDED, PLUS_ALL_DANGEROUS, PTR_MECHANISM_DEPRECATED, etc.), and an `analysis` block with the expanded include/redirect tree and the RFC 7208 §4.6.4 lookup count. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_spf_post", "x-mcp-tool": "check_spf", "summary": "Check the SPF record for a domain.", "description": "Check the SPF record for a domain. Returns the raw record, grade (A-F), the terminal `all` qualifier (resolved through redirect= chains), structured findings (NEAR_LOOKUP_LIMIT, LOOKUP_LIMIT_EXCEEDED, PLUS_ALL_DANGEROUS, PTR_MECHANISM_DEPRECATED, etc.), and an `analysis` block with the expanded include/redirect tree and the RFC 7208 §4.6.4 lookup count. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/dkim": { "get": { "operationId": "check_dkim", "x-mcp-tool": "check_dkim", "summary": "Look up a DKIM public key at ._domainkey. and validate it.", "description": "Look up a DKIM public key at ._domainkey. and validate it. Detects key revocation (empty p=), RSA key length (KEY_TOO_SHORT below 1024, KEY_WEAK below 2048), SHA-1 hash deprecation, and t=y test mode. Returns an `analysis` block with the per-key facts (key_type, key_bits, key_strength, revoked, test_mode, hash_algs). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" }, { "name": "selector", "in": "query", "required": true, "description": "DKIM selector, e.g. \"google\", \"selector1\", \"20230601\".", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,63}$", "maxLength": 63 }, "example": "google" } ] }, "post": { "operationId": "check_dkim_post", "x-mcp-tool": "check_dkim", "summary": "Look up a DKIM public key at ._domainkey. and validate it.", "description": "Look up a DKIM public key at ._domainkey. and validate it. Detects key revocation (empty p=), RSA key length (KEY_TOO_SHORT below 1024, KEY_WEAK below 2048), SHA-1 hash deprecation, and t=y test mode. Returns an `analysis` block with the per-key facts (key_type, key_bits, key_strength, revoked, test_mode, hash_algs). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "selector" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "selector": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,63}$", "maxLength": 63, "description": "DKIM selector, e.g. \"google\", \"selector1\", \"20230601\"." } } } } } } } }, "/api/v1/dmarc": { "get": { "operationId": "check_dmarc", "x-mcp-tool": "check_dmarc", "summary": "Check the _dmarc record for a domain with DUAL discovery: the RFC 7489 §6.6.3 organisational-domain ladder (what major receivers enforce today —…", "description": "Check the _dmarc record for a domain with DUAL discovery: the RFC 7489 §6.6.3 organisational-domain ladder (what major receivers enforce today — grade/verdict anchor to it) AND the RFC 9989 §4.10 DNS Tree Walk (8-query cap, psd=n/y stop rules, fewest-labels org selection) into analysis.discovery {legacy, tree_walk, diverges}. When the two methods select different policy records or org domains, DISCOVERY_DIVERGENCE (warn) fires with a one-notch grade downgrade. Also DMARCbis tag-aware: t=/np=/psd= parsed into analysis.tags, removed tags (pct/rf/ri) emit DEPRECATED_TAG, t=y emits TESTING_MODE with a one-notch downgrade. Returns the grade (A-F) with grade_reasons, a verdict (enforced/partial/monitoring/monitoring_blind/invalid/not_configured), structured findings (NO_DMARC_RECORD, MULTIPLE_DMARC_RECORDS, INVALID_TAG, POLICY_NONE, POLICY_NONE_NO_RUA, PCT_BELOW_100, RUA_MISSING_UNDER_ENFORCEMENT, SP_NOT_ENFORCED, EXTERNAL_RUA_UNAUTHORIZED, DMARC_INHERITED_FROM_ORG, TESTING_MODE, DEPRECATED_TAG, DISCOVERY_DIVERGENCE), and an `analysis` block with the lookup ladder, discovery, source (self/org), org_domain, normalised tags, per-recipient RUA/RUF external-authorisation detail (RFC 7489 §7.1), and rua_unauthorised. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_dmarc_post", "x-mcp-tool": "check_dmarc", "summary": "Check the _dmarc record for a domain with DUAL discovery: the RFC 7489 §6.6.3 organisational-domain ladder (what major receivers enforce today —…", "description": "Check the _dmarc record for a domain with DUAL discovery: the RFC 7489 §6.6.3 organisational-domain ladder (what major receivers enforce today — grade/verdict anchor to it) AND the RFC 9989 §4.10 DNS Tree Walk (8-query cap, psd=n/y stop rules, fewest-labels org selection) into analysis.discovery {legacy, tree_walk, diverges}. When the two methods select different policy records or org domains, DISCOVERY_DIVERGENCE (warn) fires with a one-notch grade downgrade. Also DMARCbis tag-aware: t=/np=/psd= parsed into analysis.tags, removed tags (pct/rf/ri) emit DEPRECATED_TAG, t=y emits TESTING_MODE with a one-notch downgrade. Returns the grade (A-F) with grade_reasons, a verdict (enforced/partial/monitoring/monitoring_blind/invalid/not_configured), structured findings (NO_DMARC_RECORD, MULTIPLE_DMARC_RECORDS, INVALID_TAG, POLICY_NONE, POLICY_NONE_NO_RUA, PCT_BELOW_100, RUA_MISSING_UNDER_ENFORCEMENT, SP_NOT_ENFORCED, EXTERNAL_RUA_UNAUTHORIZED, DMARC_INHERITED_FROM_ORG, TESTING_MODE, DEPRECATED_TAG, DISCOVERY_DIVERGENCE), and an `analysis` block with the lookup ladder, discovery, source (self/org), org_domain, normalised tags, per-recipient RUA/RUF external-authorisation detail (RFC 7489 §7.1), and rua_unauthorised. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/tls-rpt": { "get": { "operationId": "check_tls_rpt", "x-mcp-tool": "check_tls_rpt", "summary": "Check the TLS-RPT (SMTP TLS Reporting, RFC 8460) record at _smtp._tls..", "description": "Check the TLS-RPT (SMTP TLS Reporting, RFC 8460) record at _smtp._tls.. Strict §3 classification: the record must BEGIN with the case-sensitive v=TLSRPTv1 tag, more than one such record means receivers treat TLS-RPT as not implemented, and rua= is required. Validates every rua= destination syntactically (mailto:/https:// — reachability is never probed), and detects the MTA-STS and DANE prerequisites over DNS (TLSA at _25._tcp of the lowest-preference MX) with outage reported as unknown, never as absence. Returns grade (A-F) with grade_reasons, a verdict (valid/partial/invalid/not_configured), structured findings (TLS_RPT_NO_RECORD, TLS_RPT_INVALID_VERSION, TLS_RPT_MULTIPLE_RECORDS, TLS_RPT_NO_RUA, TLS_RPT_RUA_INVALID_URI, TLS_RPT_NO_VALID_RUA, TLS_RPT_NO_ENFORCEMENT_POLICY), and an `analysis` block with parsed tags, per-URI rua validation detail, and the prerequisite probe results. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_tls_rpt_post", "x-mcp-tool": "check_tls_rpt", "summary": "Check the TLS-RPT (SMTP TLS Reporting, RFC 8460) record at _smtp._tls..", "description": "Check the TLS-RPT (SMTP TLS Reporting, RFC 8460) record at _smtp._tls.. Strict §3 classification: the record must BEGIN with the case-sensitive v=TLSRPTv1 tag, more than one such record means receivers treat TLS-RPT as not implemented, and rua= is required. Validates every rua= destination syntactically (mailto:/https:// — reachability is never probed), and detects the MTA-STS and DANE prerequisites over DNS (TLSA at _25._tcp of the lowest-preference MX) with outage reported as unknown, never as absence. Returns grade (A-F) with grade_reasons, a verdict (valid/partial/invalid/not_configured), structured findings (TLS_RPT_NO_RECORD, TLS_RPT_INVALID_VERSION, TLS_RPT_MULTIPLE_RECORDS, TLS_RPT_NO_RUA, TLS_RPT_RUA_INVALID_URI, TLS_RPT_NO_VALID_RUA, TLS_RPT_NO_ENFORCEMENT_POLICY), and an `analysis` block with parsed tags, per-URI rua validation detail, and the prerequisite probe results. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/mta-sts": { "get": { "operationId": "check_mta_sts", "x-mcp-tool": "check_mta_sts", "summary": "Check MTA-STS (RFC 8461) for a domain: the _mta-sts TXT record (strict §3.1 selection — case-sensitive leading v=STSv1, exactly one record, required 1-32…", "description": "Check MTA-STS (RFC 8461) for a domain: the _mta-sts TXT record (strict §3.1 selection — case-sensitive leading v=STSv1, exactly one record, required 1-32 alphanumeric id), the policy file at https://mta-sts./.well-known/mta-sts.txt fetched WITHOUT following redirects (§3.3), strict §3.2 policy validation (version/mode/max_age required, mx required unless mode none, max_age ≤ 31557600, duplicate keys first-wins), the policy-host X.509 certificate (§3.3 — an invalid cert means compliant senders fetch no policy), and live MX coverage against the mx: patterns (§4.1 — wildcards match exactly one leftmost label; coverage is all/partial/none, partial meaning strict senders skip the uncovered hosts per §5.1). Returns grade (A-F) with grade_reasons, a verdict (enforced/testing/reporting_only/invalid/not_configured), structured findings (MTA_STS_NO_TXT_RECORD, MTA_STS_RECORD_INVALID, MULTIPLE_MTA_STS_RECORDS, MTA_STS_POLICY_UNREACHABLE, MTA_STS_POLICY_REDIRECT, MTA_STS_POLICY_INVALID, MTA_STS_CERT_INVALID, MTA_STS_MODE_NONE, MTA_STS_MODE_TESTING, MTA_STS_MX_MISMATCH, MTA_STS_MX_PARTIAL_COVERAGE, MTA_STS_MAX_AGE_TOO_LOW), and an `analysis` block (record, policy incl. fetch_stage, cert, MX coverage detail, TLS-RPT/DANE cross-signals). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_mta_sts_post", "x-mcp-tool": "check_mta_sts", "summary": "Check MTA-STS (RFC 8461) for a domain: the _mta-sts TXT record (strict §3.1 selection — case-sensitive leading v=STSv1, exactly one record, required 1-32…", "description": "Check MTA-STS (RFC 8461) for a domain: the _mta-sts TXT record (strict §3.1 selection — case-sensitive leading v=STSv1, exactly one record, required 1-32 alphanumeric id), the policy file at https://mta-sts./.well-known/mta-sts.txt fetched WITHOUT following redirects (§3.3), strict §3.2 policy validation (version/mode/max_age required, mx required unless mode none, max_age ≤ 31557600, duplicate keys first-wins), the policy-host X.509 certificate (§3.3 — an invalid cert means compliant senders fetch no policy), and live MX coverage against the mx: patterns (§4.1 — wildcards match exactly one leftmost label; coverage is all/partial/none, partial meaning strict senders skip the uncovered hosts per §5.1). Returns grade (A-F) with grade_reasons, a verdict (enforced/testing/reporting_only/invalid/not_configured), structured findings (MTA_STS_NO_TXT_RECORD, MTA_STS_RECORD_INVALID, MULTIPLE_MTA_STS_RECORDS, MTA_STS_POLICY_UNREACHABLE, MTA_STS_POLICY_REDIRECT, MTA_STS_POLICY_INVALID, MTA_STS_CERT_INVALID, MTA_STS_MODE_NONE, MTA_STS_MODE_TESTING, MTA_STS_MX_MISMATCH, MTA_STS_MX_PARTIAL_COVERAGE, MTA_STS_MAX_AGE_TOO_LOW), and an `analysis` block (record, policy incl. fetch_stage, cert, MX coverage detail, TLS-RPT/DANE cross-signals). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/bimi": { "get": { "operationId": "check_bimi", "x-mcp-tool": "check_bimi", "summary": "Check default._bimi.: parses the BIMI record, validates the SVG Tiny-PS logo, inspects the VMC chain (expiry, EKU, SCT, issuer-accepted, SAN match,…", "description": "Check default._bimi.: parses the BIMI record, validates the SVG Tiny-PS logo, inspects the VMC chain (expiry, EKU, SCT, issuer-accepted, SAN match, logotype hash), and verifies the DMARC prerequisite (p=quarantine/reject at pct=100 — the RFC 7489 reading Gmail and Apple Mail evaluate today). DMARCbis (RFC 9989) aware: t= is parsed into analysis.dmarc.t, t=y emits TESTING_MODE (warn under p=quarantine — bis receivers read it as none; info under p=reject), and a present pct= emits DEPRECATED_TAG (removed by RFC 9989 Appendix A.6, advisory only). Returns grade (A-F), structured findings, and an `analysis` block (logo/vmc/dmarc/provider_matrix). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_bimi_post", "x-mcp-tool": "check_bimi", "summary": "Check default._bimi.: parses the BIMI record, validates the SVG Tiny-PS logo, inspects the VMC chain (expiry, EKU, SCT, issuer-accepted, SAN match,…", "description": "Check default._bimi.: parses the BIMI record, validates the SVG Tiny-PS logo, inspects the VMC chain (expiry, EKU, SCT, issuer-accepted, SAN match, logotype hash), and verifies the DMARC prerequisite (p=quarantine/reject at pct=100 — the RFC 7489 reading Gmail and Apple Mail evaluate today). DMARCbis (RFC 9989) aware: t= is parsed into analysis.dmarc.t, t=y emits TESTING_MODE (warn under p=quarantine — bis receivers read it as none; info under p=reject), and a present pct= emits DEPRECATED_TAG (removed by RFC 9989 Appendix A.6, advisory only). Returns grade (A-F), structured findings, and an `analysis` block (logo/vmc/dmarc/provider_matrix). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/dane": { "get": { "operationId": "check_dane", "x-mcp-tool": "check_dane", "summary": "Check SMTP DANE / TLSA records for a domain (RFC 7672).", "description": "Check SMTP DANE / TLSA records for a domain (RFC 7672). Resolves the MX hosts (falls back to the apex when none), looks up the TLSA record at _25._tcp. over binary DoH, classifies each record (usage 0-3 / selector 0-1 / matching 0-2 per RFC 7671 §2.1), and confirms the answer carried the DNSSEC AD bit — DANE is meaningless without DNSSEC, so an unsigned TLSA answer is the dominant failure mode. Returns grade (A-F) with grade_reasons, a verdict (valid/valid_with_warnings/no_dnssec/not_configured/error), structured findings (DANE_NO_TLSA, DANE_TLSA_HOST_UNSIGNED, DANE_PKIX_TA_USED_WITHOUT_CHAIN, DANE_TLSA_EXACT_MATCH, DANE_PARTIAL_COVERAGE, DANE_TLSA_INVALID_USAGE/SELECTOR/MATCHING), and an `analysis` block (per-host TLSA records + DNSSEC status, the spec-compliance signals, and the MTA-STS cross-signal). DNS-only: it never opens a port-25 STARTTLS handshake, so it proves the TLSA records exist, are well-formed, and are DNSSEC-signed — never that they match the live cert (Hostinger and Cloudflare both block outbound 25). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_dane_post", "x-mcp-tool": "check_dane", "summary": "Check SMTP DANE / TLSA records for a domain (RFC 7672).", "description": "Check SMTP DANE / TLSA records for a domain (RFC 7672). Resolves the MX hosts (falls back to the apex when none), looks up the TLSA record at _25._tcp. over binary DoH, classifies each record (usage 0-3 / selector 0-1 / matching 0-2 per RFC 7671 §2.1), and confirms the answer carried the DNSSEC AD bit — DANE is meaningless without DNSSEC, so an unsigned TLSA answer is the dominant failure mode. Returns grade (A-F) with grade_reasons, a verdict (valid/valid_with_warnings/no_dnssec/not_configured/error), structured findings (DANE_NO_TLSA, DANE_TLSA_HOST_UNSIGNED, DANE_PKIX_TA_USED_WITHOUT_CHAIN, DANE_TLSA_EXACT_MATCH, DANE_PARTIAL_COVERAGE, DANE_TLSA_INVALID_USAGE/SELECTOR/MATCHING), and an `analysis` block (per-host TLSA records + DNSSEC status, the spec-compliance signals, and the MTA-STS cross-signal). DNS-only: it never opens a port-25 STARTTLS handshake, so it proves the TLSA records exist, are well-formed, and are DNSSEC-signed — never that they match the live cert (Hostinger and Cloudflare both block outbound 25). Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/dnssec": { "get": { "operationId": "check_dnssec", "x-mcp-tool": "check_dnssec", "summary": "Validate a domain's DNSSEC chain of trust.", "description": "Validate a domain's DNSSEC chain of trust. Pulls DS (at the parent), DNSKEY, and RRSIG over binary DoH, walks the chain zone-by-zone (root → TLD → domain) recomputing each DS digest against the published DNSKEYs (RFC 4034 §5.1.4), and cross-checks the AD bit across Cloudflare, Google, Quad9, and OpenDNS so a single resolver's caching can't mask a break. Returns grade (A-F) with grade_reasons, a verdict (signed/partial/unsigned/broken), structured findings (DNSSEC_UNSIGNED, DNSSEC_DS_MISSING_AT_PARENT, DNSSEC_DS_ALGORITHM_DEPRECATED, DNSSEC_DNSKEY_ALGORITHM_DEPRECATED, DNSSEC_RRSIG_EXPIRED, DNSSEC_BOGUS, DNSSEC_AD_BIT_MISSING), and an `analysis` block (the full chain-walk, the per-resolver validator matrix, NSEC3 iteration/opt-out, CDS/CDNSKEY publication, signing mode, root-anchor state). Unsigned is the common case and returns status \"info\" (DNSSEC is optional), not a failure; a published-but-non-validating zone returns \"fail\". Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_dnssec_post", "x-mcp-tool": "check_dnssec", "summary": "Validate a domain's DNSSEC chain of trust.", "description": "Validate a domain's DNSSEC chain of trust. Pulls DS (at the parent), DNSKEY, and RRSIG over binary DoH, walks the chain zone-by-zone (root → TLD → domain) recomputing each DS digest against the published DNSKEYs (RFC 4034 §5.1.4), and cross-checks the AD bit across Cloudflare, Google, Quad9, and OpenDNS so a single resolver's caching can't mask a break. Returns grade (A-F) with grade_reasons, a verdict (signed/partial/unsigned/broken), structured findings (DNSSEC_UNSIGNED, DNSSEC_DS_MISSING_AT_PARENT, DNSSEC_DS_ALGORITHM_DEPRECATED, DNSSEC_DNSKEY_ALGORITHM_DEPRECATED, DNSSEC_RRSIG_EXPIRED, DNSSEC_BOGUS, DNSSEC_AD_BIT_MISSING), and an `analysis` block (the full chain-walk, the per-resolver validator matrix, NSEC3 iteration/opt-out, CDS/CDNSKEY publication, signing mode, root-anchor state). Unsigned is the common case and returns status \"info\" (DNSSEC is optional), not a failure; a published-but-non-validating zone returns \"fail\". Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/mx": { "get": { "operationId": "check_mx", "x-mcp-tool": "check_mx", "summary": "Inspect a domain's MX / mail-routing posture.", "description": "Inspect a domain's MX / mail-routing posture. Resolves the apex MX RRset (priority-sorted), and for each host the A/AAAA addresses, PTR + forward-confirmed reverse DNS (FCrDNS), DANE TLSA at _25._tcp., IP-literal (RFC 5321 §5) and CNAME (RFC 2181 §10.3) violations, and the mail provider. Detects the null MX (RFC 7505), a null MX wrongly mixed with real MX, and the implicit MX via the apex A/AAAA when no MX exists (RFC 5321 §5). Probes the MTA-STS and TLS-RPT prerequisites over DNS (case-sensitive per RFC 8461/8460) with outage reported as unknown, never absence. Returns grade (A-F) with grade_reasons, a verdict (healthy/warnings/misconfigured/null_mx/no_mx/implicit_mx), structured findings (NO_MX_RECORD, MX_IMPLICIT_FALLBACK, NULL_MX, NULL_MX_WITH_OTHER, MX_POINTS_TO_IP, MX_POINTS_TO_CNAME, MX_HOSTNAME_UNRESOLVABLE, NO_PTR_RECORD, FCRDNS_MISMATCH, MX_IPV6_ONLY, MX_NO_TRANSPORT_SECURITY, MX_GATEWAY_RDNS_COSMETIC, MX_SINGLE_HOST, MX_DUPLICATE_HOST, MX_SHARED_PRIORITY, MX_MTA_STS_WITHOUT_TLS_RPT), and an `analysis` block (per-host enrichment incl. provider, ips with FCrDNS status, dane_tlsa, and the prerequisite probe results). DNSSEC AD is a UI-only signal, not gradeable through the DoH contract. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "schema": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 }, "example": "example.com" } ] }, "post": { "operationId": "check_mx_post", "x-mcp-tool": "check_mx", "summary": "Inspect a domain's MX / mail-routing posture.", "description": "Inspect a domain's MX / mail-routing posture. Resolves the apex MX RRset (priority-sorted), and for each host the A/AAAA addresses, PTR + forward-confirmed reverse DNS (FCrDNS), DANE TLSA at _25._tcp., IP-literal (RFC 5321 §5) and CNAME (RFC 2181 §10.3) violations, and the mail provider. Detects the null MX (RFC 7505), a null MX wrongly mixed with real MX, and the implicit MX via the apex A/AAAA when no MX exists (RFC 5321 §5). Probes the MTA-STS and TLS-RPT prerequisites over DNS (case-sensitive per RFC 8461/8460) with outage reported as unknown, never absence. Returns grade (A-F) with grade_reasons, a verdict (healthy/warnings/misconfigured/null_mx/no_mx/implicit_mx), structured findings (NO_MX_RECORD, MX_IMPLICIT_FALLBACK, NULL_MX, NULL_MX_WITH_OTHER, MX_POINTS_TO_IP, MX_POINTS_TO_CNAME, MX_HOSTNAME_UNRESOLVABLE, NO_PTR_RECORD, FCRDNS_MISMATCH, MX_IPV6_ONLY, MX_NO_TRANSPORT_SECURITY, MX_GATEWAY_RDNS_COSMETIC, MX_SINGLE_HOST, MX_DUPLICATE_HOST, MX_SHARED_PRIORITY, MX_MTA_STS_WITHOUT_TLS_RPT), and an `analysis` block (per-host enrichment incl. provider, ips with FCrDNS status, dane_tlsa, and the prerequisite probe results). DNSSEC AD is a UI-only signal, not gradeable through the DoH contract. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Apex domain to inspect, e.g. \"google.com\". No scheme, no path.", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } } } } } } } }, "/api/v1/email-headers": { "post": { "operationId": "analyze_email_headers", "x-mcp-tool": "analyze_email_headers", "summary": "Analyse a pasted block of raw email headers for spoofing and phishing tells.", "description": "Analyse a pasted block of raw email headers for spoofing and phishing tells. Input is the raw headers (everything up to the first blank line — \"Show original\" / \"View source\"); the message body is not required. Returns structured findings + a phishing verdict (likely_phishing/verify_sender/minor_concerns/legitimate/auth_incomplete) derived from SPF/DKIM/DMARC alignment (RFC 7489 §3.1), Microsoft composite-auth compauth reason codes (000/010 enforced failure, 601 intra-org implicit failure, 001 weak posture), ARC chain integrity (RFC 8617 §5.2), homoglyph / IDN look-alike From domains (Unicode UTS #39), header smuggling via duplicate singleton headers (RFC 5322 §3.6), display-name-as-address spoofing, hidden bidi/control characters (UAX #9), Received-chain timestamps running backward (RFC 5321 §4.4), link display-text-vs-href mismatches, originating-IP FCrDNS (RFC 8601), and RFC 8058 List-Unsubscribe deliverability posture (category:compliance, never moves the verdict). Findings include DMARC_FAILED, SPF_HARD_FAIL, DKIM_SIGNATURE_FAILED, COMPAUTH_EXPLICIT_FAILURE, COMPAUTH_INTRA_ORG_IMPLICIT_FAILURE, HOMOGLYPH_DOMAIN, DUPLICATE_HEADER, DISPLAY_NAME_SPOOFED_ADDRESS, RECEIVED_TIMESTAMPS_BACKWARD, URL_DISPLAY_MISMATCH, HIDDEN_CONTROL_CHAR, BRAND_IMPERSONATION, and more (registered in docs/finding-codes.md). `status` is the finding-severity aggregate; `verdict` is the authoritative phishing judgment; `analysis` carries the verdict object + per-mechanism authentication. For privacy the echoed `input` is a digest only (from / subject / message_id) — raw headers are never returned. Read-only.", "tags": [ "checks" ], "responses": { "200": { "description": "The check ran. `status` carries the verdict; a domain that fails a check is still a 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalResult" } } } }, "400": { "description": "Missing or malformed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded. Retriable after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The check could not be performed and retrying will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency (DNS resolver or origin) was unavailable. Retriable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "headers" ], "additionalProperties": false, "properties": { "headers": { "type": "string", "description": "Raw email headers as a single string (everything up to the first blank line — the \"Show original\" / \"View source\" output). The message body is not required.", "minLength": 1, "maxLength": 262144 } } } } } } } } }, "components": { "schemas": { "CanonicalResult": { "type": "object", "required": [ "tool", "tool_version", "schema_version", "input", "status", "findings", "records", "timestamp", "provenance" ], "properties": { "tool": { "type": "string" }, "tool_version": { "type": "string" }, "schema_version": { "type": "integer", "const": 1 }, "input": { "type": "object" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail", "info" ] }, "verdict": { "type": "string" }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "grade_reasons": { "type": "array", "items": { "type": "string" } }, "findings": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "title" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" }, "severity": { "type": "string", "enum": [ "info", "warn", "error" ] }, "title": { "type": "string" }, "explanation": { "type": "string" }, "value": { "type": "string" }, "remediation": { "type": "string" } } } }, "records": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "ttl", "data" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "ttl": { "type": "integer" }, "data": { "type": "string" } } } }, "resolvers": { "type": "array" }, "analysis": { "type": "object" }, "timestamp": { "type": "string" }, "provenance": { "type": "object", "required": [ "operated_by" ], "properties": { "operated_by": { "type": "string" } } }, "error": { "type": "object", "required": [ "code", "message", "retriable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retriable": { "type": "boolean" } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retriable" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of what went wrong." }, "retriable": { "type": "boolean", "description": "Whether repeating the identical request may succeed." }, "hint": { "type": "string", "description": "How to correct the call." }, "docs": { "type": "string", "format": "uri", "description": "Documentation for this API." } } } } } } } }