# Email Authentication Check (`email.auth_check`)

Grades a domain's MX, SPF (counting the 10-lookup limit), DMARC, DKIM and BIMI records, says whether the domain can be spoofed and lists fixes.

Docs: https://primaryapi.com/docs/api-reference/email/auth_check

- Endpoint: `POST https://api.primaryapi.com/v1/run/email.auth_check`
- Category: Validation · Platform: `email` · Kind: validation · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=email.auth_check`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `domain` | string | yes |  | max 2048 chars | Domain to check, for example "stripe.com". An email address or URL is reduced to its domain; a subdomain is checked as written. |
| `dkimSelectors` | string[] | no |  | max 20 items; items max 63 chars | Extra DKIM selectors to probe beyond the built-in list of about 20 common ones (a custom selector cannot be discovered). |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `domain` | string | Domain that was checked (an email address or URL is reduced to its domain). |
| `domainExists` | boolean | false only for NXDOMAIN, which is returned as a free miss instead. |
| `acceptsMail` | boolean | MX records (or the implicit A/AAAA fallback) exist and there is no null MX. |
| `mailProvider` | string \| null | Mail host family (Google, Microsoft, …) from the MX host names. |
| `grade` | integer | 0-100 from our own rubric: DMARC 35, SPF 25, DKIM 25, MX 10, BIMI 5. |
| `gradeLetter` | enum |  |
| `canBeSpoofed` | boolean | true until DMARC is published with p=quarantine or p=reject for all mail (pct=100). |
| `mx` | object |  |
| `mx.records` | object[] |  |
| `mx.records[].priority` | integer |  |
| `mx.records[].host` | string |  |
| `mx.provider` | string \| null |  |
| `mx.nullMx` | boolean | RFC 7505 null MX ("0 ."): the domain accepts no mail. |
| `mx.implicit` | boolean | No MX records, mail relies on the A/AAAA fallback. |
| `spf` | object |  |
| `spf.record` | string \| null |  |
| `spf.valid` | boolean |  |
| `spf.allQualifier` | enum \| null |  |
| `spf.dnsLookupCount` | integer | DNS-querying terms counted through include:/redirect= chains. |
| `spf.exceedsLookupLimit` | boolean | More than the RFC 7208 limit of 10 DNS lookups. |
| `spf.includes` | string[] |  |
| `spf.errors` | string[] |  |
| `dmarc` | object |  |
| `dmarc.record` | string \| null |  |
| `dmarc.valid` | boolean |  |
| `dmarc.policy` | enum \| null |  |
| `dmarc.subdomainPolicy` | enum \| null |  |
| `dmarc.pct` | integer \| null |  |
| `dmarc.rua` | string[] |  |
| `dmarc.ruf` | string[] |  |
| `dmarc.alignmentDkim` | enum \| null |  |
| `dmarc.alignmentSpf` | enum \| null |  |
| `dmarc.inheritedFrom` | string \| null | Organisational domain whose record applies to a subdomain without one. |
| `dkim` | object |  |
| `dkim.found` | boolean | A live key was found at one of the probed selectors; a miss does not prove DKIM is absent. |
| `dkim.selectorsChecked` | string[] |  |
| `dkim.selectors` | object[] |  |
| `dkim.selectors[].selector` | string |  |
| `dkim.selectors[].keyType` | string |  |
| `dkim.selectors[].keyBits` | integer \| null |  |
| `dkim.selectors[].testing` | boolean |  |
| `dkim.selectors[].revoked` | boolean |  |
| `bimi` | object |  |
| `bimi.record` | string \| null |  |
| `bimi.logo` | string \| null |  |
| `bimi.authority` | string \| null |  |
| `fixes` | string[] | Plain-language fixes, most important first. |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/email.auth_check" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"github.com"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "domain": "github.com",
      "domainExists": true,
      "acceptsMail": true,
      "mailProvider": "string",
      "grade": 0,
      "gradeLetter": "A",
      "canBeSpoofed": true,
      "mx": {
        "records": [
          {
            "priority": 0,
            "host": "string"
          }
        ],
        "provider": "string",
        "nullMx": true,
        "implicit": true
      },
      "spf": {
        "record": "string",
        "valid": true,
        "allQualifier": "+",
        "dnsLookupCount": 0,
        "exceedsLookupLimit": true,
        "includes": [
          "string"
        ],
        "errors": [
          "string"
        ]
      },
      "dmarc": {
        "record": "string",
        "valid": true,
        "policy": "none",
        "subdomainPolicy": "none",
        "pct": 0,
        "rua": [
          "string"
        ],
        "ruf": [
          "string"
        ],
        "alignmentDkim": "relaxed",
        "alignmentSpf": "relaxed",
        "inheritedFrom": "string"
      },
      "dkim": {
        "found": true,
        "selectorsChecked": [
          "string"
        ],
        "selectors": [
          {
            "selector": "string",
            "keyType": "string",
            "keyBits": 0,
            "testing": true,
            "revoked": true
          }
        ]
      },
      "bimi": {
        "record": "string",
        "logo": "string",
        "authority": "string"
      },
      "fixes": [
        "string"
      ]
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=email.auth_check`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

A non-existent domain (NXDOMAIN) is a free miss (reason domain_not_found). DNS failures are retried over DNS-over-HTTPS and are never charged.

