La meilleure API de vérification est celle qui tient sous la charge.

Vous brancherez du code sur cet objet pendant des années : lisez-le avant tout le reste. Un schéma réduit à une énumération oblige chaque consommateur à reconstituer la nuance que l’éditeur possédait puis a jetée.

Ce qu’il vous faut : un verdict sur lequel faire un switch, un score chiffré dont vous fixez vous-même le seuil, et des motifs exploitables par machine sous les deux. Ce sont ces motifs qui permettent de traiter différemment une adresse de rôle, une boîte pleine et un domaine qui vous a mis en greylisting, sans trois intégrations distinctes.

• Un verdict d’accessibilité stable entre versions, qui se projette proprement sur autoriser, avertir et bloquer
• Un score, pour que votre seuil soit une valeur de configuration et non une décision de l’éditeur
• Des codes de motif documentés et énumérables, pas du texte libre en anglais
• Une action recommandée, utile aux parties du produit qui ne sont pas du code
• Des indicateurs pour les cas qui vous concernent : attrape-tout, jetable, rôle, suggestion de faute de frappe

La vérification au niveau de la boîte dialogue avec un tiers en SMTP, et certains serveurs destinataires sont lents à dessein. Un contrôle unitaire est en général rapide et occasionnellement non, ce qui pose problème s’il se trouve sur le chemin critique d’une inscription.

Concevez pour cela plutôt que d’espérer. Fixez un délai côté client que vous acceptez d’afficher, traitez un dépassement comme non concluant et non comme invalide, et laissez passer l’inscription avec un marqueur au lieu de refuser un vrai client parce qu’un serveur était occupé. Revérifiez ensuite de façon asynchrone et agissez sur la seconde réponse.

Demandez à chaque éditeur son délai publié et son comportement quand il l’atteint. Un éditeur qui renvoie invalide sur son propre dépassement transforme discrètement son problème d’infrastructure en votre inscription perdue.

Il existe trois natures d’échec et elles appellent trois réactions différentes de votre code. Les confondre est la cause la plus fréquente d’une intégration de vérification qui dérape en production.

Une requête mal formée est votre bug et ne doit jamais être rejouée. Une limitation de débit ou une défaillance passagère en amont se rejoue avec un délai croissant. Et un verdict non concluant n’est pas une erreur : l’appel a réussi, la réponse est qu’aucune réponse n’était disponible, et rejouer immédiatement produira la même absence de réponse en dépensant un crédit de plus.

• Des 4xx pour vos erreurs, avec un code exploitable et stable, pas une phrase
• Un 429 accompagné d’un en-tête indiquant quand revenir, plutôt qu’un refus sec
• Des 5xx réservés aux défaillances de l’éditeur, pour que votre supervision puisse s’y fier
• Des résultats non concluants renvoyés en 200 avec un verdict inconnu, parce que c’est ce qui s’est produit

Un contrôle unitaire est synchrone et vit dans une requête. Un lot est asynchrone et vit dans une file, parfois une heure durant. Traiter le second comme le premier, c’est finir à interroger un point d’état chaque seconde pendant quarante minutes.

Vérifiez que le côté lot est une vraie API de tâches : soumission, identifiant, interrogation ou rappel, puis téléchargement. Vérifiez ce qui arrive si vous soumettez deux fois le même fichier, quel est le plafond de taille, et si l’export conserve vos colonnes. Ces trois réponses font gagner plus de temps d’ingénierie que l’écart de prix entre deux éditeurs de ce marché.

Aucun n’est intéressant jusqu’au jour où il l’est, et l’intégration est alors déjà écrite.

• La rotation des clés. Plusieurs clés actives, révocables séparément, sans interruption.
• Ne jamais appeler une API de vérification depuis le navigateur. La clé est un secret, et une clé publique est un solde de crédits offert.
• La conservation. Combien de temps l’adresse envoyée est stockée, et si vous pouvez raccourcir ce délai.
• L’idempotence à la soumission d’un lot, pour qu’une coupure réseau ne facture pas deux fois le même fichier.
• Si le même moteur alimente le tableau de bord et l’API. Sinon, votre sondage ne prouve rien sur la production.

Un jeton, un point d’entrée pour une adresse et un pour un lot. POST /v1/check_email renvoie le verdict, le score, les codes de motif et l’action recommandée ; POST /v1/bulk prend une liste et renvoie une tâche à interroger. Les deux sont documentés avec des exemples exécutables plutôt qu’avec un schéma brut.

Les clés API accompagnent n’importe quel forfait payant, mensuel ou à l’usage, au lieu de commencer à un palier dont la plupart des équipes n’ont pas besoin. Un compte gratuit vérifie dans le tableau de bord, ce qui suffit à voir la forme des réponses avant d’écrire du code.