## Endpoint

```
GET /v1/check/{email_or_domain}
```

Validates an email address (or domain) and returns a risk score, a deliverability score, and a structured reason. Accepts both a full email (`user@domain.com`) and a bare domain (`domain.com`).

## Authentication

All requests require an API key in the `Authorization` header:

```
Authorization: Bearer sv_your_key
```

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `email_or_domain` | string (path) | Full email address (`user@domain.com`) or bare domain (`domain.com`). Max 320 characters. |

Passing a full email enables local-part analysis (role accounts, random strings, suspicious patterns) in addition to domain analysis.

## Input validation

The following inputs return a `422` error:

- Empty string
- Longer than 320 characters total
- Email with more than one `@`, or local part longer than 64 characters
- Domain with spaces, an `http://` or `https://` prefix, or characters outside `[a-zA-Z0-9.-]`
- IP addresses (IPv4 or IPv6)
- Non-ASCII domains without Punycode encoding (e.g. `émail.fr` → use `xn--mail-poa.fr`)

## Response

| Field | Type | Description |
|-------|------|-------------|
| `email` | string | Masked input: `{hash[:2]}****{hash[-2:]}@domain` — local part is never exposed in plain text |
| `is_risky` | boolean | `true` if `risk_score` ≥ project threshold (default: 65) |
| `risk_score` | integer | Risk score from 0 to 100 |
| `reason` | string | Primary reason: `safe` · `disposable` · `undeliverable` · `role_account` |
| `is_free_provider` | boolean | `true` for consumer webmail providers (Gmail, Yahoo, Hotmail…) |
| `is_corporate_email` | boolean | `true` for a business domain with a professional MX configuration |
| `did_you_mean` | string \| null | Typo correction suggestion — e.g. `"gmail.com"` for input `"gmial.com"` |
| `is_alias_email` | boolean | `true` for privacy alias services (SimpleLogin, AnonAddy, Apple Hide My Email…) |
| `mx_provider_label` | string \| null | Human-readable MX provider name — e.g. `"Google Workspace"`, `"Microsoft 365"` |
| `deliverability_score` | integer | Deliverability score from 0 to 100 — probability that a real human will receive the email |

## Risk score interpretation

The higher the score, the riskier the email. The calculation method is proprietary.

| Score | Meaning | Recommended action |
|-------|---------|-------------------|
| 0–29 | Safe domain | Accept |
| 30–49 | Low risk | Accept with caution |
| 50–79 | High risk | Show a warning |
| 80–99 | Very likely disposable | Block or confirm |
| 100 | Confirmed disposable | Block |

## Deliverability score interpretation

The higher the score, the better the deliverability. The calculation method is proprietary.

| Score | Meaning |
|-------|---------|
| 80–100 | High — email is very likely to reach the inbox |
| 50–79 | Moderate — delivery is possible but not guaranteed |
| 0–49 | Low — email is unlikely to be delivered |

## Reason values

| Value | Description |
|-------|-------------|
| `safe` | No risk detected |
| `disposable` | Known or detected disposable domain |
| `undeliverable` | Domain does not exist (NXDOMAIN) or has no MX records |
| `role_account` | Local part is a role address (admin@, info@, no-reply@…) |

## Error codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `401` | Missing or invalid API key |
| `403` | Unauthorised origin (CORS restriction) |
| `422` | Invalid email or domain format |
| `429` | Quota exceeded — upgrade your plan or wait for the monthly reset |
| `500` | Internal server error — always fail open, let the user through |

See [Error codes](/docs/guides/errors) for JSON response structure and examples.