Référence de l'API de vérification d'e-mail

Authentification

POST /v1/email/validate accepte une clé publiable restreinte par origine via l'en-tête X-Api-Key — le même type de clé et le même modèle d'origines autorisées que GET /v1/geo. Tous les autres points de terminaison de cette page (lot, tâches de liste, vérification d'inscription) acceptent de nombreuses adresses ou une IP arbitraire : ils exigent donc votre clé secrète via Authorization: Bearer et ne doivent être appelés que depuis votre backend ; une clé publiable y reçoit une 403.

Exemple

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Verdicts et codes de motif

Chaque condition impose un verdict minimal ; la plus sévère l'emporte, et reasons les énumère toutes, de la plus sévère à la moins sévère. L'acceptabilité d'une adresse chez un fournisseur gratuit est laissée à votre appréciation — elle ne modifie jamais le verdict.

Vérification par lot

POST/v1/email/batch

Vérifie de 1 à 100 adresses en une seule requête, avec les mêmes contrôles et la même forme de résultat que POST /v1/email/validate, un résultat par adresse dans l'ordre d'envoi. Envoyez { "emails": [...] }. Les adresses d'un même domaine partagent une seule recherche DNS. Compte une requête par adresse sur le plafond mensuel de votre forfait ; un lot qui dépasserait le plafond est refusé en entier avec 429 monthly_limit_exceeded. Pour la limite de débit par minute, l'appel entier compte pour une seule requête. Clé secrète uniquement.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

Tâches de liste d'e-mails

POST/v1/email/jobs

Vérifie jusqu'à 100 000 adresses en arrière-plan. Envoyez du JSON { "emails": [...], "filename": "..." } ou un corps text/csv de 10 Mo au maximum : la colonne intitulée email (ou e-mail, email address, email_address ou mail, sans distinction de casse) est utilisée, ou la première colonne si aucun en-tête ne la nomme ; les séparateurs virgule, point-virgule et tabulation sont détectés. La tâche est facturée à sa création — une requête par adresse distincte (correspondance exacte), les doublons sont donc vérifiés mais facturés une seule fois — et une liste qui dépasserait votre plafond mensuel est refusée en entier. Si une partie de la tâche ne peut pas être traitée après plusieurs tentatives, la tâche est marquée failed et les crédits de la partie non traitée sont restitués. Répond 202 avec l'objet tâche. Clé secrète uniquement ; les mêmes tâches peuvent aussi être envoyées et téléchargées depuis la page Email lists du tableau de bord.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Statut d'une tâche

GET/v1/email/jobs/{id}

Renvoie le même objet tâche. Interrogez-le jusqu'à ce que status vaille completed ; ces interrogations ne sont pas facturées.

Résultats d'une tâche

GET/v1/email/jobs/{id}/results

Télécharge un CSV avec une ligne par ligne envoyée, dans l'ordre d'envoi — doublons compris. Colonnes : email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons est séparé par des points-virgules, une cellule vide signifie null, et mx_status est vide pour les adresses syntaxiquement invalides (aucune recherche n'a été faite). Une adresse invalide commençant par =, +, - ou @ est préfixée d'une apostrophe afin que les tableurs ne l'exécutent pas comme une formule. 409 tant que la tâche n'est pas terminée, 410 une fois expirée. Le téléchargement n'est pas facturé.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Vérification d'inscription

POST/v1/signup/check

Évalue une inscription à partir de son adresse e-mail et de son IP en un seul appel, depuis votre backend lors de la soumission du formulaire (un verdict calculé dans le navigateur peut être falsifié). Envoyez { "email": "...", "ip": "...", "userAgent": "..." } — userAgent est facultatif. La réponse contient le résultat complet de la vérification d'e-mail (email), le pays et l'ASN de l'IP et — sur les forfaits incluant les données de sécurité — ses indicateurs VPN/Tor/centre de données/menace (ip), l'âge du domaine de l'e-mail en jours d'après les données publiques d'enregistrement (RDAP) (emailDomainAgeDays, null s'il est inconnu et pour les grands fournisseurs grand public), un score de 0 à 100 (la somme des poids des motifs ci-dessous, plafonnée à 100) et un verdict : reject à partir de 60, review à partir de 25, sinon accept. Sur un forfait sans données de sécurité, ip.security vaut null, le score n'utilise que les signaux e-mail et reasons inclut ip_security_unavailable. Compte comme une requête. Clé secrète uniquement.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Limites

Chaque adresse vérifiée compte comme une requête sur le plafond mensuel partagé de votre forfait — une vérification unitaire, chaque adresse d'un lot, chaque adresse distincte d'une tâche de liste — et une vérification d'inscription compte comme une requête. Les lots et les tâches de liste sont acceptés ou refusés en entier, jamais traités partiellement. La limite de débit par minute compte les appels HTTP, pas les éléments : un lot de jusqu'à 100 IP ou adresses e-mail compte pour une seule requête, tandis que chaque élément compte toujours séparément dans le plafond mensuel de requêtes. Les envois et résultats des tâches de liste sont supprimés 7 jours après la création de la tâche. Les recherches DNS disposent d'un court délai : en cas d'échec ou d'expiration, le résultat se dégrade en mx.status unknown et motif dns_unavailable plutôt qu'en erreur. Les données de domaines jetables proviennent de la fusion de trois listes open source maintenues par la communauté, actualisées toutes les quelques heures et complétées par les serveurs de messagerie observés desservant des domaines listés — voir sources de données. Un fournisseur jetable très récent peut ne pas encore être signalé. Toutes les vérifications portent sur le domaine et l'adresse : aucune boîte aux lettres n'est contactée, donc aucun résultat n'établit qu'une boîte existe, à qui elle appartient, ni que le courrier y parviendra.