> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Validity

> Dedicated deliverability check for an email address disposable and mailbox verification only, without the full web-profile enrichment.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="email" type="string" required>
  The email address to validate. The legacy key `e` is still accepted.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL (API Key) theme={"dark"}
  curl -X POST "https://encrata.com/api/agent/email-validity" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "test@example.com"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://encrata.com/api/agent/email-validity",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"email": "test@example.com"},
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch("https://encrata.com/api/agent/email-validity", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "test@example.com" }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

## Response

Returns the four-status deliverability model plus metadata that explains and
enriches the verdict (metadata never changes the public `status`, except a
corroborated catch-all being promoted to `valid`).

<ResponseField name="email" type="string">
  The email address that was checked (normalized to lowercase).
</ResponseField>

<ResponseField name="status" type="string">
  The public verdict one of `valid`, `invalid`, `catch-all`, or `risky`.
</ResponseField>

<ResponseField name="reason" type="string">
  Machine-readable explanation, e.g. `deliverable`, `syntax`, `disposable`,
  `null_mx`, `no_mail_route`, `hard_reject`, `mailbox_full`, `unverifiable`,
  `greylist_unresolved`, `ip_blocked`, `unreachable`, `catch_all`, or
  `catchall_corroborated`.
</ResponseField>

<ResponseField name="confidence" type="string">
  Provider-calibrated confidence in the verdict `high`, `medium`, or `low`
  (e.g. a bare `250` from Yahoo/O365 is reported as lower confidence).
</ResponseField>

<ResponseField name="role" type="boolean">
  `true` when the local part is a role/shared mailbox (e.g. `support@`,
  `info@`). Role accounts still deliver this is a flag only.
</ResponseField>

<ResponseField name="did_you_mean" type="string">
  A suggested correction when a likely typo is detected (e.g. `gmial.com`).
</ResponseField>

<ResponseField name="domain" type="string">
  The domain part of the address.
</ResponseField>

<ResponseField name="provider" type="string">
  Mailbox provider classification `google`, `microsoft`, `yahoo`, or `other`.
</ResponseField>

<ResponseField name="mx" type="string[]">
  The domain's resolved mail servers (MX hosts) in preference order.
</ResponseField>

<ResponseField name="domain_trust" type="object">
  The domain's outbound-security posture (non-voting metadata): `grade` (A–F),
  `spf`, `dmarc`, `dmarc_policy`, `mta_sts`, and `tls_rpt`, plus the raw DNS
  records behind them (`spf_record`, `dmarc_record`, `tls_rpt_record`,
  `mta_sts_record`) when present.
</ResponseField>

<ResponseField name="person_signal" type="object">
  OSINT corroboration: `count` of independent hits and the `sources` that hit
  (`hibp`, `gravatar`, `github`, `gitlab`, `pgp`). A positive signal on a
  catch-all domain promotes the status to `valid`.
</ResponseField>

<ResponseField name="smtp" type="object">
  Technical probe detail when available: `mx_host`, `code`, `message`,
  `catch_all`, and `greylisted`.
</ResponseField>

<ResponseField name="validity" type="string" deprecated>
  Legacy mirror of `status`, retained for backward compatibility.
</ResponseField>

### Example response

```json theme={"dark"}
{
  "email": "jane@example.com",
  "status": "valid",
  "reason": "deliverable",
  "confidence": "high",
  "role": false,
  "domain": "example.com",
  "provider": "google",
  "mx": ["aspmx.l.google.com", "alt1.aspmx.l.google.com"],
  "domain_trust": { "grade": "A", "spf": true, "dmarc": true, "dmarc_policy": "reject", "mta_sts": "enforce", "tls_rpt": true },
  "person_signal": { "count": 2, "sources": ["hibp", "gravatar"] },
  "smtp": { "mx_host": "aspmx.l.google.com", "code": 250, "catch_all": false, "greylisted": false },
  "checked_at": "2026-07-14T10:00:00Z",
  "validity": "valid",
  "credits": 1
}
```

<Note>
  The in-app equivalent is `POST /api/email/validity` (session-authenticated).
  Both charge like a standard lookup. The MCP `validate_email` tool returns the
  same shape and is free.
</Note>