# Mail Domain Check Public API

> A rate-limited JSON API for public MX, SPF, DKIM, DMARC, MTA-STS, TLS-RPT, PTR, and CAA diagnostics. No account or API key is required.

## Request

Send a JSON `POST` to `https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/api/scan`:

```sh
curl --fail-with-body -sS \
  'https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/api/scan?utm_source=api-docs' \
  -H 'Content-Type: application/json' \
  --data '{"domain":"example.com"}'
```

Request fields:

- `domain` is required. Supply a bare domain, not a URL, path, email address, or IP.
- `dkimSelector` is optional. DKIM is evaluated only when this real selector is known.
- `sendingIp` is optional. Supply the actual public IPv4 or IPv6 outbound address to evaluate PTR and A/AAAA forward confirmation.

For an IP-only PTR and forward-confirmation check, send a JSON `POST` to `/api/ptr-check`:

```sh
curl --fail-with-body -sS \
  'https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/api/ptr-check?utm_source=api-docs' \
  -H 'Content-Type: application/json' \
  --data '{"sendingIp":"8.8.8.8"}'
```

The focused response includes safe `PtrDiagnostics`: `ipVersion`, `ptrRecordCount`, `forwardRecordType`, bounded forward-query counts, `forwardAddressCount`, and `forwardConfirmed`. It never returns PTR hostnames or raw DNS answers.

## Response

Successful responses include the normalized domain, scan time, duration, score, grade, pass/warn/fail/info counts, bilingual summary, eight bilingual check summaries, and a disclaimer. The SPF check also includes a safe `diagnostics` object with `spfRecordCount`, `dnsLookupCount`, the fixed `dnsLookupLimit` of 10, and `lookupComplete`. A null count means that no unique SPF policy could be expanded; a false completion flag means the observed count may be a lower bound.

The DMARC check follows the current RFC 9989 bounded DNS Tree Walk. Its safe diagnostics include `directRecordCount`, `policyFound`, `policyDomain`, inherited `policyTag` and `policy`, alignment modes, aggregate-reporting presence, test mode, historic `pct` presence, the query count, and discarded record conflicts. It never returns raw DMARC TXT data or aggregate-report destinations.

The MTA-STS check reports the STSv1 announcement count and validity, fixed-path HTTPS fetch state, policy validity, mode, `maxAge`, and MX pattern count. The companion TLS-RPT check reports record state and aggregate `mailto` or HTTPS destination counts. It never returns announcement records, policy contents, MX patterns, or report destinations.

When `dkimSelector` is supplied, the DKIM check includes safe selector metadata: `recordCount`, normalized `keyType`, `publicKeyPresent`, `revoked`, `testMode`, `strictIdentity`, `emailServiceAllowed`, and `sha256Allowed`. It never returns the raw TXT record or public-key value.

When `sendingIp` is supplied, the PTR check includes safe counts and forward-confirmation state. The same PTR diagnostics are returned by `/api/ptr-check` without requiring a domain.

The public response intentionally omits complete DNS/HTTPS evidence and remediation actions. It also omits raw SPF, DMARC, MTA-STS, and TLS-RPT records, policy contents, MX patterns, report destinations, expanded include targets, raw DKIM records, and public-key material.

`X-RateLimit-Remaining` reports the remaining requests in the current source-address window. More than 30 scans in 60 seconds returns `429` with `Retry-After`.

## Privacy and clients

Free analytics retain irreversible domain and visitor hashes plus aggregate result and source metrics, not raw domains or sending IPs. The optional sending IP is used for the current DNS check and is retained with report data only after checkout.

Cross-origin browser requests are not supported. Use the same-origin browser scanner, the published Node.js CLI, or a server-side HTTP client. The endpoint is for interactive diagnostics, not bulk enumeration, monitoring, or unsolicited data collection.

## Machine contract

- OpenAPI: `https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/openapi.json`
- Human documentation: `https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/developers/api/`
- CLI: `https://mail-domain-check-zac2.coral-ibis-2405.chatgpt.site/developers/cli/`

Results describe public configuration at scan time. They do not guarantee inbox placement and do not replace a complete security or compliance audit.