{ "openapi": "3.1.0", "info": { "title": "DMARC SPF DKIM Lookup and Email Domain Audit API", "description": "Check SPF, DKIM, DMARC, MX, BIMI, MTA-STS, TLS-RPT, and email-domain authentication posture in one API call.", "version": "1.0.0", "x-long-description": "RapidAPI-ready email domain authentication audit API.\n\nThe main buyer-friendly endpoint is `GET /v1/email-auth-audit/{domain}` so users can enter a domain and click Run.\n\nThe API returns structured lookup results, score, grade, risk level, provider hints, fix recommendations, and optional raw DNS evidence." }, "paths": { "/trust/v1/free/audits/domain": { "post": { "tags": [ "free" ], "summary": "Audit a domain \u2014 BASIC", "description": "**Tier: BASIC** \u00b7 **Costs: 0 paid audit units**\n\nAudit one domain and return its score, grade, risk level, and top prioritized findings. The BASIC response intentionally favors high-signal issues and may omit low-priority informational items on otherwise strong domains. Upgrade to a paid plan for the complete findings list, bulk audits, compare, fix-plan, and richer reporting.", "operationId": "free_post_domain_audit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "0" } }, "X-Audit-Score": { "description": "Overall audit score (0-100) for single-domain audit responses.", "schema": { "type": "string", "example": "82" } }, "X-Audit-Grade": { "description": "Letter grade for single-domain audit responses.", "schema": { "type": "string", "example": "B" } }, "X-Audit-ID": { "description": "Unique audit identifier for single-domain audit responses.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeAuditResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/audits/domain": { "post": { "tags": [ "pro" ], "summary": "Audit a domain \u2014 Paid", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 1 audit**\n\nFull audit: score, grade, all findings, risk summary, score breakdown, provider analysis, assessment confidence, coverage summary, and recommendations.", "operationId": "pro_post_domain_audit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-Score": { "description": "Overall audit score (0-100) for single-domain audit responses.", "schema": { "type": "string", "example": "82" } }, "X-Audit-Grade": { "description": "Letter grade for single-domain audit responses.", "schema": { "type": "string", "example": "B" } }, "X-Audit-ID": { "description": "Unique audit identifier for single-domain audit responses.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/audits/domain/{domain}": { "get": { "tags": [ "pro" ], "summary": "Audit a domain \u2014 Paid (GET)", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 1 audit**\n\nGET convenience form. Full findings, score breakdown, and provider analysis. Pass DKIM selectors as repeated `?dkim_selectors=` params.", "operationId": "pro_get_domain_audit", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } }, { "name": "dkim_selectors", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "DKIM selectors to check (repeat for multiple).", "default": [], "title": "Dkim Selectors" }, "description": "DKIM selectors to check (repeat for multiple)." }, { "name": "check_mta_sts_policy", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Check Mta Sts Policy" } }, { "name": "check_bimi", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Check Bimi" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" } } }, "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-Score": { "description": "Overall audit score (0-100) for single-domain audit responses.", "schema": { "type": "string", "example": "82" } }, "X-Audit-Grade": { "description": "Letter grade for single-domain audit responses.", "schema": { "type": "string", "example": "B" } }, "X-Audit-ID": { "description": "Unique audit identifier for single-domain audit responses.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/audits/domains": { "post": { "tags": [ "pro" ], "summary": "Audit multiple domains \u2014 bulk", "description": "**Tier: ULTRA / MEGA** \u00b7 **Costs: N audits** (one per successfully audited domain; per-item validation failures are returned in the payload and are not billed)\n\nAudit up to 50 domains in one request. Set `include_reports=false` when you only need top-line per-domain previews plus the aggregate summary, not nested full reports. `X-Audit-Units-Consumed` reports the exact charge.", "operationId": "pro_bulk_domain_audit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__trust_auditor__schemas__BulkAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-IDs": { "description": "Comma-separated audit identifiers represented by composite responses such as bulk, compare, fix-plan, or report rendering when audit IDs are available.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAuditResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/audits/compare": { "post": { "tags": [ "pro" ], "summary": "Compare two audit reports", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 0\u20132 audits**\n\nDiff two audit results and surface improvements, regressions, and unchanged findings. Both sides must represent the same normalized domain. If DKIM selector methodology, optional check coverage, or provider-analysis context change between runs, the response includes comparability warnings and neutral coverage deltas so you can distinguish methodology drift from real posture change. Costs 0 if both sides supply a pre-existing report, 1 per side that triggers a fresh audit. `X-Audit-Units-Consumed` reports the actual charge.", "operationId": "pro_compare_audits", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditCompareRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-IDs": { "description": "Comma-separated audit identifiers represented by composite responses such as bulk, compare, fix-plan, or report rendering when audit IDs are available.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditComparisonResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/audits/fix-plan": { "post": { "tags": [ "pro" ], "summary": "Get a remediation plan", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 0\u20131 audits**\n\nGenerate a prioritized, step-by-step remediation plan. Costs 0 if you supply a pre-existing `report`; costs 1 if you supply a `request` (triggering a fresh audit). `X-Audit-Units-Consumed` reports the actual charge.", "operationId": "pro_get_fix_plan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__trust_auditor__schemas__FixPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-IDs": { "description": "Comma-separated audit identifiers represented by composite responses such as bulk, compare, fix-plan, or report rendering when audit IDs are available.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemediationPlan" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/trust/v1/pro/providers": { "get": { "tags": [ "pro" ], "summary": "List supported email providers", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 0 audits**\n\nReturns curated provider profiles the engine knows about. Use the `id` as `provider_context.provider` in audit requests. Any DKIM selector examples are discovery hints only, not authoritative inventories.", "operationId": "pro_list_providers", "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "0" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderListResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } } } } }, "/trust/v1/pro/findings/catalog": { "get": { "tags": [ "pro" ], "summary": "List all finding definitions", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 0 audits**\n\nComplete catalog of every finding ID the engine can emit \u2014 use this to build suppression rules, dashboards, or alert integrations. Some findings include `contextual_notes` describing known severity/status adjustments made from surrounding evidence.", "operationId": "pro_get_findings_catalog", "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "0" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingCatalogResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } } } } }, "/trust/v1/pro/reports/domain": { "post": { "tags": [ "pro" ], "summary": "Render an audit report", "description": "**Tier: PRO / ULTRA / MEGA** \u00b7 **Costs: 0\u20131 audits**\n\nRender an audit as HTML or structured JSON with executive summary, findings, score breakdown, assessment confidence, and coverage notes. `format=\"html\"` returns JSON with the HTML string in `content`; it does not change the HTTP response media type to `text/html`. Supply **either**:\n- `request`: `{\"domain\": \"example.com\"}` \u2014 triggers a fresh audit (costs 1 audit)\n- `report`: a pre-existing `AuditResponse` object \u2014 renders immediately (costs 0 audits)\n\n`X-Audit-Units-Consumed` reports the actual charge.", "operationId": "pro_render_domain_report", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "X-Audit-Units-Consumed": { "description": "Number of paid audit units consumed by this request. Requests that do not bill an audit return 0.", "schema": { "type": "string", "example": "1" } }, "X-Audit-IDs": { "description": "Comma-separated audit identifiers represented by composite responses such as bulk, compare, fix-plan, or report rendering when audit IDs are available.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "403": { "description": "In protected production deployments, direct origin calls without RapidAPI forwarding are rejected. RapidAPI marketplace consumers authenticate through RapidAPI and should not be shown or asked to send `X-RapidAPI-Proxy-Secret` themselves.", "content": { "application/json": { "example": { "detail": "Forbidden: invalid or missing proxy secret." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "meta" ], "summary": "Health check", "description": "Operational readiness endpoint.", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Health Health Get" } } } } } } }, "/v1/provider-presets": { "get": { "tags": [ "lookup" ], "summary": "Provider presets", "description": "Return provider-aware DNS hints, common MX patterns, SPF includes, and common DKIM selector presets.", "operationId": "provider_presets_v1_provider_presets_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/findings-catalog": { "get": { "tags": [ "lookup" ], "summary": "Findings catalog", "description": "Return the catalog of stable finding IDs used across audit responses.", "operationId": "findings_catalog_v1_findings_catalog_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/dmarc-lookup/{domain}": { "get": { "tags": [ "lookup" ], "summary": "DMARC lookup", "description": "Lookup and parse the DMARC TXT record for a domain.", "operationId": "dmarc_lookup_v1_dmarc_lookup__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/spf-lookup/{domain}": { "get": { "tags": [ "lookup" ], "summary": "SPF lookup", "description": "Lookup and parse the SPF TXT record for a domain, including best-effort DNS lookup counting.", "operationId": "spf_lookup_v1_spf_lookup__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/dkim-check": { "post": { "tags": [ "lookup" ], "summary": "DKIM check", "description": "Check exact or provider-preset DKIM selectors for a domain.", "operationId": "dkim_check_v1_dkim_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DKIMCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/mx-lookup/{domain}": { "get": { "tags": [ "lookup" ], "summary": "MX lookup", "description": "Lookup MX records and guess the likely provider based on MX and SPF signals.", "operationId": "mx_lookup_v1_mx_lookup__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/email-auth-audit/{domain}": { "get": { "tags": [ "audit" ], "summary": "Email authentication audit", "description": "Main RapidAPI-friendly audit endpoint. Enter a domain and click Run.", "operationId": "email_auth_audit_v1_email_auth_audit__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } }, { "name": "include_raw", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Raw" } }, { "name": "include_fix_plan", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Fix Plan" } }, { "name": "dkim_selectors", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated selector list.", "title": "Dkim Selectors" }, "description": "Comma-separated selector list." }, { "name": "provider_hint", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Hint" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/bulk/email-auth-audit": { "post": { "tags": [ "audit" ], "summary": "Bulk email authentication audit", "description": "Audit multiple domains in one synchronous request. Continues processing when one domain fails.", "operationId": "bulk_email_auth_audit_v1_bulk_email_auth_audit_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__BulkAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/fix-plan": { "post": { "tags": [ "audit" ], "summary": "Fix plan", "description": "Generate a provider-aware staged fix plan from an audit status summary.", "operationId": "fix_plan_v1_fix_plan_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__FixPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/bulk/jobs/{job_id}": { "get": { "tags": [ "audit" ], "summary": "Bulk job status", "description": "Return the status of an asynchronous bulk audit job.", "operationId": "bulk_job_status_v1_bulk_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/dns-records/{domain}": { "get": { "tags": [ "lookup" ], "summary": "DNS records snapshot", "description": "Return TXT and MX records for a domain.", "operationId": "dns_records_v1_dns_records__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/mta-sts-check/{domain}": { "get": { "tags": [ "lookup" ], "summary": "MTA-STS check", "description": "Check for an MTA-STS DNS record and optional hosted policy file.", "operationId": "mta_sts_check_v1_mta_sts_check__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tls-rpt-check/{domain}": { "get": { "tags": [ "lookup" ], "summary": "TLS-RPT check", "description": "Check for a TLS-RPT record at `_smtp._tls.`.", "operationId": "tls_rpt_check_v1_tls_rpt_check__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/bimi-check/{domain}": { "get": { "tags": [ "lookup" ], "summary": "BIMI check", "description": "Check for a BIMI TXT record at `default._bimi.`.", "operationId": "bimi_check_v1_bimi_check__domain__get", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/compare-audits": { "post": { "tags": [ "audit" ], "summary": "Compare audits", "description": "Run two audits and compare top-line score and grade.", "operationId": "compare_audits_v1_compare_audits_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareAuditsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AuditCompareRequest": { "properties": { "previous": { "$ref": "#/components/schemas/CompareInput" }, "current": { "$ref": "#/components/schemas/CompareInput" } }, "type": "object", "required": [ "previous", "current" ], "title": "AuditCompareRequest", "example": { "current": { "request": { "dkim_selectors": [ "provider-issued-selector-1" ], "domain": "example.com" } }, "previous": { "request": { "domain": "example.com" } } } }, "AuditComparisonResponse": { "properties": { "compared_domain": { "type": "string", "title": "Compared Domain", "description": "Normalized domain shared by both compared reports." }, "previous_score": { "type": "integer", "title": "Previous Score" }, "current_score": { "type": "integer", "title": "Current Score" }, "score_delta": { "type": "integer", "title": "Score Delta" }, "previous_grade": { "type": "string", "title": "Previous Grade" }, "current_grade": { "type": "string", "title": "Current Grade" }, "grade_changed": { "type": "boolean", "title": "Grade Changed" }, "added_findings": { "items": { "$ref": "#/components/schemas/FindingDelta" }, "type": "array", "title": "Added Findings" }, "resolved_findings": { "items": { "$ref": "#/components/schemas/FindingDelta" }, "type": "array", "title": "Resolved Findings" }, "worsened_findings": { "items": { "$ref": "#/components/schemas/FindingDelta" }, "type": "array", "title": "Worsened Findings" }, "improved_findings": { "items": { "$ref": "#/components/schemas/FindingDelta" }, "type": "array", "title": "Improved Findings" }, "unchanged_findings": { "items": { "$ref": "#/components/schemas/FindingDelta" }, "type": "array", "title": "Unchanged Findings" }, "recommendation_delta": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object", "title": "Recommendation Delta" }, "comparability_warnings": { "items": { "type": "string" }, "type": "array", "title": "Comparability Warnings", "description": "Warnings about changed methodology or context that can make score deltas less trustworthy." }, "summary": { "type": "string", "title": "Summary" }, "operator_summary": { "items": { "type": "string" }, "type": "array", "title": "Operator Summary" }, "check_deltas": { "items": { "$ref": "#/components/schemas/CheckDelta" }, "type": "array", "title": "Check Deltas" }, "top_regressions": { "items": { "type": "string" }, "type": "array", "title": "Top Regressions", "description": "Highest-impact comparable posture regressions. Coverage-only changes stay in `comparability_warnings` and `check_deltas`." }, "top_improvements": { "items": { "type": "string" }, "type": "array", "title": "Top Improvements", "description": "Highest-impact comparable posture improvements. Coverage-only changes stay in `comparability_warnings` and `check_deltas`." } }, "type": "object", "required": [ "compared_domain", "previous_score", "current_score", "score_delta", "previous_grade", "current_grade", "grade_changed", "added_findings", "resolved_findings", "worsened_findings", "improved_findings", "unchanged_findings", "recommendation_delta", "summary" ], "title": "AuditComparisonResponse", "example": { "added_findings": [ { "check": "dkim", "current_status": "not_applicable", "id": "dkim.none_valid" } ], "check_deltas": [ { "check": "dmarc", "current_status": "warn", "impact": "unchanged", "previous_status": "warn" } ], "comparability_warnings": [ "DKIM selector inputs changed between reports (previous: not_provided [none]; current: provided [provider-issued-selector-1]). Score differences may reflect evaluation coverage rather than a real posture change." ], "compared_domain": "example.com", "current_grade": "A+", "current_score": 95, "grade_changed": false, "improved_findings": [], "operator_summary": [ "Comparison includes methodology changes; interpret score deltas cautiously.", "Raw score was unchanged across non-equivalent inputs (A+ -> A+)." ], "previous_grade": "A+", "previous_score": 95, "recommendation_delta": { "added": [], "resolved": [], "unchanged": [ "Add rua=mailto: to receive aggregate reports." ] }, "resolved_findings": [ { "check": "dkim", "id": "dkim.not_evaluated", "previous_status": "not_applicable" } ], "score_delta": 0, "summary": "Comparison includes methodology changes; interpret score deltas cautiously. Raw score moved by +0 (A+ -> A+).", "top_improvements": [], "top_regressions": [], "unchanged_findings": [ { "check": "dmarc", "current_status": "warn", "id": "dmarc.missing_rua", "previous_status": "warn" } ], "worsened_findings": [] } }, "AuditRequest": { "properties": { "domain": { "type": "string", "maxLength": 253, "minLength": 1, "title": "Domain", "description": "Email domain to audit (e.g. 'example.com').", "examples": [ "example.com" ] }, "dkim_selectors": { "items": { "type": "string" }, "type": "array", "title": "Dkim Selectors", "description": "Exact DKIM selectors to check. Use selector names copied from the sending platform when possible because catalog examples are not authoritative for every domain. If omitted, the API may conservatively test common selectors only when a single stable provider match exists; exact provider-issued selectors still produce the most authoritative result.", "examples": [ [ "provider-issued-selector-1", "provider-issued-selector-2" ] ] }, "check_mta_sts_policy": { "type": "boolean", "title": "Check Mta Sts Policy", "description": "Whether to fetch and validate the MTA-STS policy file over HTTPS.", "default": true }, "check_bimi": { "type": "boolean", "title": "Check Bimi", "description": "Whether to check for a BIMI DNS record. This is syntax-only validation; it does not verify logo hosting, SVG profile compliance, trademark eligibility, or VMC/CMC certificate trust.", "default": true }, "provider_context": { "anyOf": [ { "$ref": "#/components/schemas/ProviderContext" }, { "type": "null" } ], "description": "Optional declared provider for conservative provider-aware analysis." } }, "type": "object", "required": [ "domain" ], "title": "AuditRequest", "description": "Body of ``POST /v1/free/audits/domain`` and ``POST /v1/pro/audits/domain``.", "example": { "check_bimi": true, "check_mta_sts_policy": true, "dkim_selectors": [ "provider-issued-selector-1" ], "domain": "google.com", "provider_context": { "provider": "google_workspace" } } }, "AuditResponse": { "properties": { "audit_id": { "type": "string", "title": "Audit Id", "description": "Unique identifier for this audit run (UUID-4)." }, "audited_at": { "type": "string", "format": "date-time", "title": "Audited At", "description": "UTC timestamp when the audit was executed (ISO-8601)." }, "domain": { "type": "string", "title": "Domain", "description": "Original domain as submitted." }, "normalized_domain": { "type": "string", "title": "Normalized Domain", "description": "Domain after normalization (punycode)." }, "scope": { "$ref": "#/components/schemas/Scope", "description": "What entity was evaluated and known limitations." }, "mail_flow_profile": { "type": "string", "title": "Mail Flow Profile", "description": "How to interpret the apex domain's visible mail role: active_mail_domain, apex_non_mail_protected, apex_inbound_disabled, apex_outbound_or_subdomain_mail_possible, or mail_role_unknown.", "default": "active_or_unknown" }, "mail_flow_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mail Flow Note", "description": "Human-readable note explaining whether the score represents active sender/receiver readiness or protective DNS posture for a non-mail apex." }, "score": { "type": "integer", "maximum": 100.0, "minimum": 0.0, "title": "Score", "description": "Overall trust score (0-100). Read alongside risk, assessment confidence, and coverage notes; critical anti-spoofing gaps or provisional DKIM coverage can cap the top-line result." }, "score_version": { "type": "string", "title": "Score Version", "description": "Scoring model version (for reproducibility)." }, "score_breakdown": { "additionalProperties": { "$ref": "#/components/schemas/ScoreBreakdownEntry" }, "type": "object", "title": "Score Breakdown", "description": "Per-check score breakdown showing earned vs possible normalised points. Included checks sum to roughly 100 possible points; excluded checks show 0 possible with an explanatory note." }, "grade": { "type": "string", "title": "Grade", "description": "Letter grade: A+ / A / B / C / D / F. Interpret alongside risk, assessment confidence, and coverage summary rather than as a standalone safety verdict." }, "risk": { "$ref": "#/components/schemas/RiskSummary", "description": "Commercial-grade risk assessment." }, "findings": { "items": { "$ref": "#/components/schemas/Finding" }, "type": "array", "title": "Findings" }, "recommendations": { "items": { "type": "string" }, "type": "array", "title": "Recommendations", "description": "Prioritised list of actionable recommendations." }, "raw": { "additionalProperties": true, "type": "object", "title": "Raw", "description": "Raw data from each check, keyed by check category." }, "provider_analysis": { "anyOf": [ { "$ref": "#/components/schemas/ProviderAnalysis" }, { "type": "null" } ] } }, "type": "object", "required": [ "domain", "normalized_domain", "scope", "score", "score_version", "score_breakdown", "grade", "risk", "findings", "recommendations", "raw" ], "title": "AuditResponse", "example": { "audit_id": "f554d658-3b8b-4fd3-96d1-d9a8157d291b", "audited_at": "2026-04-13T05:21:12.534282Z", "domain": "example.com", "findings": [ { "check": "mx", "evidence": "MX record is explicitly set to '.' (null MX), indicating the domain does not accept inbound email.", "id": "mx.null_mx", "severity": "low", "status": "not_applicable", "title": "Null MX Published (No Inbound Mail)" }, { "check": "spf", "evidence": "SPF record found with '-all' (hard-fail). Record: v=spf1 -all", "id": "spf.pass", "severity": "low", "status": "pass", "title": "SPF Valid" }, { "check": "dmarc", "evidence": "Record: v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s | Issues: No 'rua' tag \u2014 aggregate reports will not be received.", "fix": "Add rua=mailto: to receive aggregate reports.", "id": "dmarc.missing_rua", "severity": "medium", "status": "warn", "title": "DMARC Missing Aggregate Reporting URI" } ], "grade": "A+", "mail_flow_note": "The apex publishes null MX and SPF -all. Treat the score as protective DNS posture for a non-mail apex, not active sender-program readiness.", "mail_flow_profile": "apex_non_mail_protected", "normalized_domain": "example.com", "raw": { "_meta": { "dkim_selectors_supplied": [], "request_flags": { "check_bimi": true, "check_mta_sts_policy": true } }, "dmarc": { "records": [ "v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s" ], "tags": { "adkim": "s", "aspf": "s", "p": "reject", "sp": "reject", "v": "DMARC1" } }, "mx": { "null_mx": true, "records": [ "" ] }, "spf": { "records": [ "v=spf1 -all" ] } }, "recommendations": [ "Add rua=mailto: to receive aggregate reports." ], "risk": { "assessment_confidence": "high", "coverage_summary": "The apex appears intentionally configured as a non-mail domain (null MX + SPF -all). Interpret the score as protective DNS posture, not active sender-program readiness.", "deliverability_risk": "Low \u2014 the domain publishes a null MX, so inbound delivery is intentionally disabled at the apex.", "enforcement_status": "partial", "executive_summary": "The domain received a score of 95/100 (grade A+). The apex appears intentionally configured as a protected non-mail domain; remaining findings are monitoring or coverage gaps, not evidence that an active sender program is only partially enforced.", "risk_level": "low", "spoofing_risk": "Low \u2014 the apex publishes null MX and SPF -all, so it appears intentionally configured not to receive or send mail from the apex.", "top_3_actions": [ "Add rua=mailto: to receive aggregate reports." ] }, "scope": { "entity_type": "root_domain", "evaluated_entity": "example.com", "scope_note": "This audit evaluates the domain's publicly visible email trust posture based on DNS records and, where applicable, the MTA-STS policy file. Some production sending infrastructure may live on subdomains or use provider-managed selectors not fully visible from this scope. DKIM evaluation requires explicit selectors. BIMI validation is syntax-only (VMC certificate verification is not performed)." }, "score": 95, "score_breakdown": { "dkim": { "earned": 0.0, "note": "Not applicable to this domain, so it is excluded from the normalized 0-100 breakdown.", "possible": 0.0, "status": "not_applicable" }, "dmarc": { "earned": 45.0, "possible": 50.0, "status": "warn" }, "mx": { "earned": 0.0, "note": "Not applicable to this domain, so it is excluded from the normalized 0-100 breakdown.", "possible": 0.0, "status": "not_applicable" }, "spf": { "earned": 50.0, "possible": 50.0, "status": "pass" } }, "score_version": "11" } }, "BulkAuditItem": { "properties": { "domain": { "type": "string", "title": "Domain" }, "dkim_selectors": { "items": { "type": "string" }, "type": "array", "title": "Dkim Selectors" } }, "type": "object", "required": [ "domain" ], "title": "BulkAuditItem" }, "BulkAuditResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BulkAuditResultItem" }, "type": "array", "title": "Results" }, "summary": { "$ref": "#/components/schemas/BulkSummary" } }, "type": "object", "required": [ "results", "summary" ], "title": "BulkAuditResponse", "example": { "results": [ { "assessment_confidence": "high", "audit_id": "baacf6a8-062c-4d4f-b8ef-0abb5f1a7a3e", "coverage_summary": "The apex appears intentionally configured as a non-mail domain (null MX + SPF -all). Interpret the score as protective DNS posture, not active sender-program readiness.", "domain": "example.com", "grade": "A+", "mail_flow_note": "The apex publishes null MX and SPF -all. Treat the score as protective DNS posture for a non-mail apex, not active sender-program readiness.", "mail_flow_profile": "apex_non_mail_protected", "risk_level": "low", "score": 95, "success": true } ], "summary": { "common_blocker_categories": { "dmarc": 1 }, "critical_failure_domains": [], "domains_dkim_not_evaluated": [], "domains_missing_dmarc": [], "domains_missing_or_invalid_dmarc": [], "domains_with_invalid_dmarc": [], "domains_with_weak_spf": [], "enforcement_ready_domains": [], "failure_count": 0, "finding_counts": { "dmarc.missing_rua": 1, "mx.null_mx": 1, "spf.pass": 1 }, "grade_counts": { "A+": 1 }, "highest_deliverability_risk_domains": [], "highest_spoofing_risk_domains": [], "prioritized_next_actions": [ "Address recurring blocker category: dmarc:1" ], "provider_mismatch_domains": [], "score_band_counts": { "90-100": 1 }, "strongest_domains": [ "example.com" ], "success_count": 1, "top_recommendations": [ "example.com: Add rua=mailto: to receive aggregate reports." ], "total_domains": 1, "weakest_domains": [] } } }, "BulkAuditResultItem": { "properties": { "domain": { "type": "string", "title": "Domain" }, "success": { "type": "boolean", "title": "Success" }, "report": { "anyOf": [ { "$ref": "#/components/schemas/AuditResponse" }, { "type": "null" } ] }, "audit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audit Id", "description": "Audit identifier for successful bulk items." }, "score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Score", "description": "Top-line score preview for successful bulk items." }, "grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grade", "description": "Top-line grade preview for successful bulk items." }, "risk_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risk Level", "description": "Top-line risk level preview for successful bulk items." }, "assessment_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assessment Confidence", "description": "Evidence-confidence preview for successful bulk items." }, "coverage_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coverage Summary", "description": "Coverage note preview for successful bulk items." }, "mail_flow_profile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mail Flow Profile", "description": "Visible mail-role classification for successful bulk items." }, "mail_flow_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mail Flow Note", "description": "Short note explaining whether the score reflects active mail readiness or protective posture." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "domain", "success" ], "title": "BulkAuditResultItem" }, "BulkSummary": { "properties": { "total_domains": { "type": "integer", "title": "Total Domains" }, "success_count": { "type": "integer", "title": "Success Count" }, "failure_count": { "type": "integer", "title": "Failure Count" }, "grade_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Grade Counts" }, "score_band_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Score Band Counts" }, "finding_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Finding Counts" }, "critical_failure_domains": { "items": { "type": "string" }, "type": "array", "title": "Critical Failure Domains" }, "domains_missing_dmarc": { "items": { "type": "string" }, "type": "array", "title": "Domains Missing Dmarc", "description": "Domains with no DMARC record at `_dmarc.`." }, "domains_with_invalid_dmarc": { "items": { "type": "string" }, "type": "array", "title": "Domains With Invalid Dmarc", "description": "Domains where `_dmarc.` exists but does not contain a valid DMARC record." }, "domains_missing_or_invalid_dmarc": { "items": { "type": "string" }, "type": "array", "title": "Domains Missing Or Invalid Dmarc", "description": "Combined list of domains with missing or invalid DMARC posture." }, "domains_with_weak_spf": { "items": { "type": "string" }, "type": "array", "title": "Domains With Weak Spf" }, "domains_dkim_not_evaluated": { "items": { "type": "string" }, "type": "array", "title": "Domains Dkim Not Evaluated" }, "strongest_domains": { "items": { "type": "string" }, "type": "array", "title": "Strongest Domains" }, "weakest_domains": { "items": { "type": "string" }, "type": "array", "title": "Weakest Domains" }, "top_recommendations": { "items": { "type": "string" }, "type": "array", "title": "Top Recommendations" }, "prioritized_next_actions": { "items": { "type": "string" }, "type": "array", "title": "Prioritized Next Actions" }, "highest_spoofing_risk_domains": { "items": { "type": "string" }, "type": "array", "title": "Highest Spoofing Risk Domains" }, "highest_deliverability_risk_domains": { "items": { "type": "string" }, "type": "array", "title": "Highest Deliverability Risk Domains" }, "enforcement_ready_domains": { "items": { "type": "string" }, "type": "array", "title": "Enforcement Ready Domains" }, "common_blocker_categories": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Common Blocker Categories" }, "provider_mismatch_domains": { "items": { "type": "string" }, "type": "array", "title": "Provider Mismatch Domains" } }, "type": "object", "required": [ "total_domains", "success_count", "failure_count", "grade_counts", "score_band_counts", "finding_counts", "critical_failure_domains", "domains_with_weak_spf", "domains_dkim_not_evaluated", "strongest_domains", "weakest_domains", "top_recommendations", "prioritized_next_actions" ], "title": "BulkSummary" }, "CatalogFinding": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable finding identifier (e.g. 'spf.missing')." }, "check": { "type": "string", "title": "Check", "description": "Parent check category." }, "title": { "type": "string", "title": "Title" }, "severity": { "type": "string", "title": "Severity" }, "typical_status": { "type": "string", "title": "Typical Status" }, "description": { "type": "string", "title": "Description" }, "fix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fix" }, "rfc_refs": { "items": { "type": "string" }, "type": "array", "title": "Rfc Refs", "description": "Relevant RFC or specification references." }, "contextual_notes": { "items": { "type": "string" }, "type": "array", "title": "Contextual Notes", "description": "Known context-dependent rules that can soften or intensify the emitted severity/status for this finding ID." } }, "type": "object", "required": [ "id", "check", "title", "severity", "typical_status", "description", "rfc_refs" ], "title": "CatalogFinding", "description": "One entry in ``GET /v1/pro/findings/catalog``." }, "CheckDelta": { "properties": { "check": { "type": "string", "title": "Check" }, "previous_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Status" }, "current_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Status" }, "impact": { "type": "string", "title": "Impact", "description": "improved | regressed | unchanged | coverage_changed" } }, "type": "object", "required": [ "check", "previous_status", "current_status", "impact" ], "title": "CheckDelta" }, "CompareAuditsRequest": { "properties": { "previous_domain": { "type": "string", "maxLength": 2048, "title": "Previous Domain" }, "current_domain": { "type": "string", "maxLength": 2048, "title": "Current Domain" } }, "type": "object", "required": [ "previous_domain", "current_domain" ], "title": "CompareAuditsRequest", "example": { "current_domain": "example.net", "previous_domain": "example.com" } }, "CompareInput": { "oneOf": [ { "required": [ "report" ] }, { "required": [ "request" ] } ], "properties": { "report": { "anyOf": [ { "$ref": "#/components/schemas/AuditResponse" }, { "type": "null" } ] }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AuditRequest" }, { "type": "null" } ] } }, "type": "object", "title": "CompareInput" }, "DKIMCheckRequest": { "properties": { "domain": { "type": "string", "maxLength": 2048, "title": "Domain", "description": "Domain to check." }, "selectors": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "title": "Selectors", "description": "Exact or likely DKIM selectors to test." }, "provider_hint": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Provider Hint", "description": "Optional provider hint used for selector presets." } }, "type": "object", "required": [ "domain" ], "title": "DKIMCheckRequest", "example": { "domain": "example.com", "provider_hint": "google_workspace", "selectors": [ "google", "selector1", "selector2", "default", "mail", "k1" ] } }, "Finding": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable, granular finding identifier (e.g. 'spf.missing')." }, "check": { "type": "string", "title": "Check", "description": "Check category (spf | dmarc | dkim | mx | mta_sts | tls_rpt | bimi)." }, "title": { "type": "string", "title": "Title" }, "status": { "type": "string", "title": "Status", "description": "pass | fail | warn | info | not_evaluated | not_applicable" }, "severity": { "type": "string", "title": "Severity", "description": "critical | high | medium | low" }, "evidence": { "type": "string", "title": "Evidence" }, "fix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fix" } }, "type": "object", "required": [ "id", "check", "title", "status", "severity", "evidence" ], "title": "Finding" }, "FindingCatalogResponse": { "properties": { "count": { "type": "integer", "title": "Count" }, "findings": { "items": { "$ref": "#/components/schemas/CatalogFinding" }, "type": "array", "title": "Findings" } }, "type": "object", "required": [ "count", "findings" ], "title": "FindingCatalogResponse", "description": "Response from ``GET /v1/pro/findings/catalog``." }, "FindingDelta": { "properties": { "id": { "type": "string", "title": "Id" }, "check": { "type": "string", "title": "Check" }, "previous_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Status" }, "current_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Status" } }, "type": "object", "required": [ "id", "check", "previous_status", "current_status" ], "title": "FindingDelta" }, "FreeAuditResponse": { "properties": { "audit_id": { "type": "string", "title": "Audit Id", "description": "Unique identifier for this audit run (UUID-4)." }, "domain": { "type": "string", "title": "Domain", "description": "Original domain as submitted." }, "score": { "type": "integer", "maximum": 100.0, "minimum": 0.0, "title": "Score", "description": "Overall trust score (0-100). Read alongside risk level, assessment confidence, and coverage summary; provisional DKIM coverage or critical anti-spoofing gaps can cap the top-line result." }, "grade": { "type": "string", "title": "Grade", "description": "Letter grade: A+ / A / B / C / D / F. Interpret alongside risk level, assessment confidence, and coverage summary rather than as a standalone safety verdict." }, "risk_level": { "type": "string", "title": "Risk Level", "description": "Aggregate risk level: critical | high | medium | low." }, "enforcement_status": { "type": "string", "title": "Enforcement Status", "description": "Email authentication enforcement posture: none | partial | full." }, "mail_flow_profile": { "type": "string", "title": "Mail Flow Profile", "description": "Visible mail-role classification for the audited apex domain.", "default": "active_or_unknown" }, "mail_flow_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mail Flow Note", "description": "Short note explaining how to interpret the score for this mail role." }, "assessment_confidence": { "type": "string", "title": "Assessment Confidence", "description": "How complete the evidence was for this assessment: high | medium | low.", "default": "high" }, "coverage_summary": { "type": "string", "title": "Coverage Summary", "description": "What was directly evaluated versus left partially covered or provisional.", "default": "All configured checks were evaluated from the available DNS evidence." }, "top_findings": { "items": { "$ref": "#/components/schemas/Finding" }, "type": "array", "title": "Top Findings", "description": "Up to 5 prioritized findings. The response prefers critical/high actionable issues, then backfills medium-severity gaps when needed. Low-priority informational findings may be omitted on otherwise strong domains. Upgrade to Pro for the complete findings list." }, "top_recommendations": { "items": { "type": "string" }, "type": "array", "title": "Top Recommendations", "description": "Up to 3 highest-priority recommendations. Upgrade to Pro for the full prioritized list and a step-by-step fix plan." }, "upgrade_note": { "type": "string", "title": "Upgrade Note", "description": "Description of additional capabilities available in the Pro tier.", "default": "Upgrade to Pro for full findings, bulk audits, compare, and fix-plan endpoints." } }, "type": "object", "required": [ "audit_id", "domain", "score", "grade", "risk_level", "enforcement_status", "top_findings", "top_recommendations" ], "title": "FreeAuditResponse", "description": "Trimmed response for the free-tier single-domain audit endpoint.\n\nContains the score, grade, risk level, and a prioritized subset of findings.\nUpgrade to Pro for the full findings list, score breakdown, provider analysis,\nbulk audits, compare, and remediation fix-plans.", "example": { "assessment_confidence": "high", "audit_id": "eba3de04-9956-4b62-bcb8-23b82eabba1d", "coverage_summary": "The apex appears intentionally configured as a non-mail domain (null MX + SPF -all). Interpret the score as protective DNS posture, not active sender-program readiness.", "domain": "example.com", "enforcement_status": "partial", "grade": "A+", "mail_flow_note": "The apex publishes null MX and SPF -all. Treat the score as protective DNS posture for a non-mail apex, not active sender-program readiness.", "mail_flow_profile": "apex_non_mail_protected", "risk_level": "low", "score": 95, "top_findings": [ { "check": "dmarc", "evidence": "Record: v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s | Issues: No 'rua' tag \u2014 aggregate reports will not be received.", "fix": "Add rua=mailto: to receive aggregate reports.", "id": "dmarc.missing_rua", "severity": "medium", "status": "warn", "title": "DMARC Missing Aggregate Reporting URI" } ], "top_recommendations": [ "Add rua=mailto: to receive aggregate reports." ], "upgrade_note": "Upgrade to Pro for full findings, bulk audits, compare, and fix-plan endpoints." } }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ProviderAnalysis": { "properties": { "provider": { "type": "string", "title": "Provider", "description": "Primary provider/profile selected by declared context or DNS heuristics. For inferred analysis this is not a complete account inventory; inspect `matched_providers`, `secondary_providers`, warnings, and verification steps." }, "supported": { "type": "boolean", "title": "Supported" }, "source": { "type": "string", "title": "Source", "description": "How the provider was identified: declared | inferred.", "default": "inferred" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings" }, "evidence_matches": { "items": { "type": "string" }, "type": "array", "title": "Evidence Matches" }, "evidence_mismatches": { "items": { "type": "string" }, "type": "array", "title": "Evidence Mismatches" }, "matched_providers": { "items": { "type": "string" }, "type": "array", "title": "Matched Providers", "description": "All provider profiles whose SPF evidence matched this domain. Useful when multiple sending platforms appear in the same SPF record." }, "secondary_providers": { "items": { "type": "string" }, "type": "array", "title": "Secondary Providers", "description": "Additional matched providers beyond the primary `provider` field." }, "inference_confidence": { "type": "string", "title": "Inference Confidence", "description": "Confidence in the inferred provider heuristic: high | medium | low.", "default": "high" }, "expected_dkim_selectors": { "items": { "type": "string" }, "type": "array", "title": "Expected Dkim Selectors", "description": "Common selector names or patterns associated with this provider. Treat them as discovery hints to verify, not authoritative selector inventories." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes" }, "mismatch_level": { "type": "string", "title": "Mismatch Level", "description": "none | low | medium | high", "default": "none" }, "verification_steps": { "items": { "type": "string" }, "type": "array", "title": "Verification Steps" } }, "type": "object", "required": [ "provider", "supported" ], "title": "ProviderAnalysis" }, "ProviderContext": { "properties": { "provider": { "type": "string", "title": "Provider", "description": "Declared mail provider/profile. Accepted canonical ids include: amazon_ses, google_workspace, klaviyo, mailchimp, microsoft_365, sendgrid. Aliases from `/v1/pro/providers` are also accepted and normalized.", "examples": [ "google_workspace" ] } }, "type": "object", "required": [ "provider" ], "title": "ProviderContext" }, "ProviderListResponse": { "properties": { "count": { "type": "integer", "title": "Count" }, "providers": { "items": { "$ref": "#/components/schemas/ProviderSummary" }, "type": "array", "title": "Providers" } }, "type": "object", "required": [ "count", "providers" ], "title": "ProviderListResponse", "description": "Response from ``GET /v1/pro/providers``." }, "ProviderSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "display_name": { "type": "string", "title": "Display Name" }, "aliases": { "items": { "type": "string" }, "type": "array", "title": "Aliases", "description": "Alternative strings accepted as provider_context.provider." }, "expected_dkim_selectors": { "items": { "type": "string" }, "type": "array", "title": "Expected Dkim Selectors", "description": "Common selector names or patterns for this provider. Treat them as discovery hints to verify, not universal truths." }, "expected_mx_tokens": { "items": { "type": "string" }, "type": "array", "title": "Expected Mx Tokens", "description": "Common inbound MX hostname fragments used only as conservative provider inference hints." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes" } }, "type": "object", "required": [ "id", "display_name", "aliases", "expected_dkim_selectors", "notes" ], "title": "ProviderSummary", "description": "One entry in ``GET /v1/pro/providers``." }, "RemediationAction": { "properties": { "issue_id": { "type": "string", "title": "Issue Id" }, "priority": { "type": "string", "enum": [ "p0", "p1", "p2", "p3" ], "title": "Priority" }, "actionability": { "type": "string", "enum": [ "exact", "template", "manual_review" ], "title": "Actionability" }, "why_it_matters": { "type": "string", "title": "Why It Matters" }, "dns_name": { "type": "string", "title": "Dns Name" }, "record_type": { "type": "string", "title": "Record Type" }, "operation": { "type": "string", "enum": [ "add", "replace", "remove", "review" ], "title": "Operation" }, "proposed_value_template": { "type": "string", "title": "Proposed Value Template" }, "dependency_notes": { "items": { "type": "string" }, "type": "array", "title": "Dependency Notes" }, "confidence_note": { "type": "string", "title": "Confidence Note" }, "confidence_level": { "type": "string", "enum": [ "high", "medium", "low" ], "title": "Confidence Level", "default": "medium" }, "rationale": { "type": "string", "title": "Rationale", "default": "" }, "evidence_basis": { "items": { "type": "string" }, "type": "array", "title": "Evidence Basis" }, "preconditions": { "items": { "type": "string" }, "type": "array", "title": "Preconditions" }, "application_risk": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "Application Risk", "default": "medium" }, "verify_after_change": { "items": { "type": "string" }, "type": "array", "title": "Verify After Change" }, "rollout_strategy": { "type": "string", "enum": [ "safe_now", "stage_carefully" ], "title": "Rollout Strategy", "default": "stage_carefully" } }, "type": "object", "required": [ "issue_id", "priority", "actionability", "why_it_matters", "dns_name", "record_type", "operation", "proposed_value_template", "confidence_note" ], "title": "RemediationAction" }, "RemediationPlan": { "properties": { "domain": { "type": "string", "title": "Domain" }, "exact_remediations": { "items": { "$ref": "#/components/schemas/RemediationAction" }, "type": "array", "title": "Exact Remediations" }, "template_remediations": { "items": { "$ref": "#/components/schemas/RemediationAction" }, "type": "array", "title": "Template Remediations" }, "manual_review_needed": { "items": { "$ref": "#/components/schemas/RemediationAction" }, "type": "array", "title": "Manual Review Needed" }, "priority_summary": { "items": { "type": "string" }, "type": "array", "title": "Priority Summary" } }, "type": "object", "required": [ "domain", "exact_remediations", "template_remediations", "manual_review_needed", "priority_summary" ], "title": "RemediationPlan", "example": { "domain": "example.com", "exact_remediations": [], "manual_review_needed": [], "priority_summary": [ "P1: dmarc.missing_rua (safe_now, low risk)" ], "template_remediations": [ { "actionability": "template", "application_risk": "low", "confidence_level": "medium", "confidence_note": "Built from the observed DMARC tags, but the aggregate-reporting mailbox must be chosen and monitored by the operator.", "dependency_notes": [ "Preserve the existing DMARC policy tags while adding rua." ], "dns_name": "_dmarc.example.com", "evidence_basis": [ "finding:dmarc.missing_rua" ], "issue_id": "dmarc.missing_rua", "operation": "replace", "preconditions": [ "Choose and monitor the aggregate-reporting mailbox before publishing the updated DMARC record." ], "priority": "p1", "proposed_value_template": "v=DMARC1; p=reject; sp=reject; rua=mailto:; adkim=s; aspf=s", "rationale": "Aggregate reports help validate ongoing DMARC enforcement and spot alignment drift.", "record_type": "TXT", "rollout_strategy": "safe_now", "verify_after_change": [ "dig +short TXT _dmarc.example.com", "Confirm aggregate DMARC reports begin arriving at the configured mailbox." ], "why_it_matters": "DMARC reporting visibility is missing even though policy enforcement exists." } ] } }, "ReportRequest": { "oneOf": [ { "required": [ "report" ] }, { "required": [ "request" ] } ], "properties": { "report": { "anyOf": [ { "$ref": "#/components/schemas/AuditResponse" }, { "type": "null" } ], "description": "Pre-existing audit report to render (costs 0 audits)." }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AuditRequest" }, { "type": "null" } ], "description": "Fresh domain audit request (costs 1 audit). Provide either 'report' or 'request', not both." }, "format": { "type": "string", "enum": [ "html", "structured" ], "title": "Format", "description": "Output format: 'html' returns a complete HTML document as a string in the JSON `content` field; 'structured' returns a dict in `content`.", "default": "html" } }, "type": "object", "title": "ReportRequest", "description": "Body of ``POST /v1/pro/reports/domain``.\n\nSupply **either** ``report`` (a pre-existing ``AuditResponse``, costs 0 audits)\n**or** ``request`` (an ``AuditRequest`` triggering a fresh audit, costs 1 audit).", "example": { "format": "html", "request": { "domain": "example.com" } } }, "ReportResponse": { "properties": { "format": { "type": "string", "title": "Format", "description": "The format that was rendered ('html' or 'structured')." }, "content": { "title": "Content", "description": "Rendered report content. HTML format is returned as a string inside this JSON field." } }, "type": "object", "required": [ "format", "content" ], "title": "ReportResponse", "description": "Response from ``POST /v1/pro/reports/domain``.", "example": { "content": { "assessment_confidence": "high", "coverage_summary": "The apex appears intentionally configured as a non-mail domain (null MX + SPF -all).", "domain": "example.com", "executive_summary": "The apex appears intentionally configured as a protected non-mail domain; remaining findings are monitoring or coverage gaps.", "findings": [ { "check": "dmarc", "evidence": "Record: v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s | Issues: No 'rua' tag \u2014 aggregate reports will not be received.", "fix": "Add rua=mailto: to receive aggregate reports.", "id": "dmarc.missing_rua", "severity": "medium", "status": "warn", "title": "DMARC Missing Aggregate Reporting URI" } ], "grade": "A+", "header": { "assessment_confidence": "high", "domain": "example.com", "grade": "A+", "mail_flow_profile": "apex_non_mail_protected", "risk_level": "low", "score": 95 }, "mail_flow_profile": "apex_non_mail_protected", "recommendations": [ "Add rua=mailto: to receive aggregate reports." ], "risk_level": "low", "score": 95, "score_breakdown": { "dmarc": { "earned": 45.0, "possible": 50.0, "status": "warn" }, "spf": { "earned": 50.0, "possible": 50.0, "status": "pass" } }, "title": "Email Domain Trust Report: example.com" }, "format": "structured" } }, "RiskSummary": { "properties": { "executive_summary": { "type": "string", "title": "Executive Summary", "description": "One-paragraph human-readable overview of the domain's email trust posture." }, "risk_level": { "type": "string", "title": "Risk Level", "description": "critical | high | medium | low" }, "spoofing_risk": { "type": "string", "title": "Spoofing Risk", "description": "How exposed the domain is to email spoofing." }, "deliverability_risk": { "type": "string", "title": "Deliverability Risk", "description": "How likely legitimate email is to be rejected or junked." }, "enforcement_status": { "type": "string", "title": "Enforcement Status", "description": "none | partial | full" }, "assessment_confidence": { "type": "string", "title": "Assessment Confidence", "description": "How complete the evidence was for this assessment: high | medium | low.", "default": "high" }, "coverage_summary": { "type": "string", "title": "Coverage Summary", "description": "What was directly evaluated versus left partially covered or provisional.", "default": "All configured checks were evaluated from the available DNS evidence." }, "top_3_actions": { "items": { "type": "string" }, "type": "array", "title": "Top 3 Actions", "description": "The three highest-priority actions the domain owner should take." } }, "type": "object", "required": [ "executive_summary", "risk_level", "spoofing_risk", "deliverability_risk", "enforcement_status", "top_3_actions" ], "title": "RiskSummary" }, "Scope": { "properties": { "evaluated_entity": { "type": "string", "title": "Evaluated Entity", "description": "The exact domain string that was audited." }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type of entity evaluated: root_domain | subdomain.", "default": "root_domain" }, "scope_note": { "type": "string", "title": "Scope Note", "description": "Human-readable disclaimer about what this audit covers and what it does not." } }, "type": "object", "required": [ "evaluated_entity", "scope_note" ], "title": "Scope" }, "ScoreBreakdownEntry": { "properties": { "earned": { "type": "number", "title": "Earned", "description": "Normalised points earned for this check." }, "possible": { "type": "number", "title": "Possible", "description": "Maximum normalised points available for this check within the current 0-100 scoring basis. Checks excluded from scoring report 0.0 here and explain why in `note`." }, "status": { "type": "string", "title": "Status", "description": "Finding status used for scoring." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note", "description": "Explanation when the check was excluded or partially evaluated." } }, "type": "object", "required": [ "earned", "possible", "status" ], "title": "ScoreBreakdownEntry" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "app__schemas__BulkAuditRequest": { "properties": { "domains": { "items": { "type": "string" }, "type": "array", "maxItems": 25, "minItems": 1, "title": "Domains", "description": "List of domains to audit." }, "include_raw": { "type": "boolean", "title": "Include Raw", "description": "Include raw DNS evidence in nested audit results where available.", "default": false }, "include_fix_plan": { "type": "boolean", "title": "Include Fix Plan", "description": "Include staged fix plans for each domain when supported.", "default": false }, "provider_hints": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Provider Hints", "description": "Optional domain-to-provider hint map." }, "webhook_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Webhook Url", "description": "Optional webhook URL to receive asynchronous results." } }, "type": "object", "required": [ "domains" ], "title": "BulkAuditRequest", "example": { "domains": [ "example.com", "clientdomain.com", "startup.io" ], "include_fix_plan": false, "include_raw": false, "provider_hints": { "clientdomain.com": "microsoft_365", "example.com": "google_workspace" }, "webhook_url": "https://hooks.example.com/audit-results" } }, "app__schemas__FixPlanRequest": { "properties": { "domain": { "type": "string", "maxLength": 2048, "title": "Domain", "description": "Domain the plan applies to." }, "provider_hint": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Provider Hint", "description": "Optional provider hint for provider-aware guidance." }, "audit": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Audit", "description": "Compact top-line audit statuses." }, "goal": { "type": "string", "enum": [ "safe_monitoring", "safe_enforcement", "maximum_protection", "non_sending_domain", "agency_report" ], "title": "Goal", "default": "safe_enforcement" } }, "type": "object", "required": [ "domain", "audit" ], "title": "FixPlanRequest", "example": { "audit": { "bimi": "missing", "dkim": "unknown", "dmarc": "warning", "mta_sts": "missing", "mx": "pass", "spf": "pass", "tls_rpt": "missing" }, "domain": "example.com", "goal": "safe_enforcement", "provider_hint": "google_workspace" } }, "app__trust_auditor__schemas__BulkAuditRequest": { "properties": { "domains": { "items": { "$ref": "#/components/schemas/BulkAuditItem" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Domains" }, "default_dkim_selectors": { "items": { "type": "string" }, "type": "array", "title": "Default Dkim Selectors" }, "check_mta_sts_policy": { "type": "boolean", "title": "Check Mta Sts Policy", "default": true }, "check_bimi": { "type": "boolean", "title": "Check Bimi", "default": true }, "include_reports": { "type": "boolean", "title": "Include Reports", "description": "When false, omit nested full audit reports and return per-domain previews only to reduce payload size.", "default": true }, "provider_context": { "anyOf": [ { "$ref": "#/components/schemas/ProviderContext" }, { "type": "null" } ] } }, "type": "object", "required": [ "domains" ], "title": "BulkAuditRequest", "example": { "check_bimi": true, "check_mta_sts_policy": true, "default_dkim_selectors": [ "provider-issued-selector-1", "provider-issued-selector-2" ], "domains": [ { "dkim_selectors": [ "provider-issued-selector-1" ], "domain": "example.com" }, { "domain": "example.org" } ], "include_reports": false, "provider_context": { "provider": "microsoft_365" } } }, "app__trust_auditor__schemas__FixPlanRequest": { "oneOf": [ { "required": [ "report" ] }, { "required": [ "request" ] } ], "properties": { "report": { "anyOf": [ { "$ref": "#/components/schemas/AuditResponse" }, { "type": "null" } ] }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AuditRequest" }, { "type": "null" } ] } }, "type": "object", "title": "FixPlanRequest", "example": { "request": { "domain": "example.com", "provider_context": { "provider": "amazon_ses" } } } } } }, "servers": [ { "url": "https://email-domain-trust-auditor.p.rapidapi.com" } ] }