## Endpoint

```
GET /v1/check/{email_ou_domaine}
```

Valide une adresse email (ou un domaine seul) et retourne un score de risque, un score de délivrabilité, et une raison structurée. Accepte un email complet (`user@domain.com`) ou un domaine seul (`domain.com`).

## Authentification

Toutes les requêtes nécessitent une clé API dans le header `Authorization` :

```
Authorization: Bearer sv_votre_cle
```

## Paramètres

| Paramètre | Type | Description |
|-----------|------|-------------|
| `email_ou_domaine` | string (path) | Adresse email complète (`user@domain.com`) ou domaine seul (`domain.com`). Max 320 caractères. |

Passer un email complet active l'analyse de la partie locale (comptes rôle, chaînes aléatoires, patterns suspects) en plus de l'analyse du domaine.

## Validation des entrées

Les entrées suivantes retournent une erreur `422` :

- Chaîne vide
- Plus de 320 caractères au total
- Email avec plus d'un `@`, ou partie locale de plus de 64 caractères
- Domaine avec des espaces, un préfixe `http://` ou `https://`, ou des caractères hors `[a-zA-Z0-9.-]`
- Adresses IP (IPv4 ou IPv6)
- Domaines non-ASCII sans encodage Punycode (ex : `émail.fr` → utiliser `xn--mail-poa.fr`)

## Réponse

| Champ | Type | Description |
|-------|------|-------------|
| `email` | string | Entrée masquée : `{hash[:2]}****{hash[-2:]}@domaine` — la partie locale n'est jamais exposée en clair |
| `is_risky` | boolean | `true` si `risk_score` ≥ seuil projet (défaut : 65) |
| `risk_score` | integer | Score de risque de 0 à 100 |
| `reason` | string | Raison principale : `safe` · `disposable` · `undeliverable` · `role_account` |
| `is_free_provider` | boolean | `true` pour les webmails grand public (Gmail, Yahoo, Hotmail…) |
| `is_corporate_email` | boolean | `true` pour un domaine d'entreprise avec configuration MX professionnelle |
| `did_you_mean` | string \| null | Suggestion de correction de typo — ex : `"gmail.com"` pour `"gmial.com"` |
| `is_alias_email` | boolean | `true` pour les services d'alias de confidentialité (SimpleLogin, AnonAddy, Apple Hide My Email…) |
| `mx_provider_label` | string \| null | Nom lisible du provider MX — ex : `"Google Workspace"`, `"Microsoft 365"` |
| `deliverability_score` | integer | Score de délivrabilité de 0 à 100 — probabilité qu'un humain réel reçoive l'email |

## Interprétation du score de risque

Plus le score est élevé, plus l'email est risqué. La méthode de calcul est propriétaire.

| Score | Signification | Action recommandée |
|-------|--------------|-------------------|
| 0–29 | Domaine sûr | Accepter |
| 30–49 | Faible risque | Accepter avec vigilance |
| 50–79 | Risque élevé | Afficher un avertissement |
| 80–99 | Très probablement jetable | Bloquer ou confirmer |
| 100 | Jetable confirmé | Bloquer |

## Interprétation du score de délivrabilité

Plus le score est élevé, meilleure est la délivrabilité. La méthode de calcul est propriétaire.

| Score | Signification |
|-------|--------------|
| 80–100 | Élevée — l'email a de très bonnes chances d'atteindre la boîte de réception |
| 50–79 | Modérée — la livraison est possible mais non garantie |
| 0–49 | Faible — l'email a peu de chances d'être délivré |

## Valeurs de reason

| Valeur | Description |
|--------|-------------|
| `safe` | Aucun risque détecté |
| `disposable` | Domaine jetable connu ou détecté |
| `undeliverable` | Domaine inexistant (NXDOMAIN) ou sans enregistrements MX |
| `role_account` | Partie locale de type compte rôle (admin@, info@, no-reply@…) |

## Codes d'erreur

| Code | Description |
|------|-------------|
| `200` | Succès |
| `401` | Clé API manquante ou invalide |
| `403` | Origine non autorisée (restriction CORS) |
| `422` | Format d'email ou de domaine invalide |
| `429` | Quota dépassé — changer de plan ou attendre la remise à zéro mensuelle |
| `500` | Erreur interne — toujours fail open, laisser l'utilisateur passer |

Voir [Codes d'erreur](/fr/docs/guides/errors) pour la structure JSON et les exemples.