Vérification d'e-mails en masse API : un workflow pratique par tâches groupées

Vérification d'e-mails en masse API : un workflow pratique par tâches groupées

La question : vous disposez d'une longue liste d'adresses dans votre propre système. Comment l'envoyer par lots via l'API FairValid, gérer les erreurs en toute sécurité et récupérer les résultats sans perdre le fil de vos crédits ?

Réponse courte : commencez dans le sandbox avec une clé de test. Divisez ensuite la liste en tâches de 5 000 adresses maximum et attribuez à chaque tâche sa propre clé d'idempotence. Soumettez chaque tâche avec une clé Live, vérifiez son statut et parcourez les résultats page par page selon le verdict. Traitez les vérifications en attente, les échecs techniques et les résultats Inconnu comme trois situations distinctes.

Éléments vérifiés le 13 novembre 2026, à partir de la référence API, du guide des résultats et des règles relatives aux crédits de FairValid.

Étape 1 : développez d'abord avec le sandbox

La référence API indique de créer une clé de test dans la section Clés API, de la conserver sur votre serveur et de la définir dans votre environnement avec l'URL de base. Les clés de test fonctionnent avec des adresses réservées sur le domaine example.com. Elles n'effectuent aucun appel aux fournisseurs et ne consomment aucun crédit. Les clés de test accèdent à leurs propres tâches simulées.

Les tâches de test renvoient des états déterministes : terminée, en attente, échouée ou annulée. Consultez la référence API pour connaître les adresses exactes du sandbox, et utilisez-les pour vérifier que votre code gère ces états. Ces cas ne montrent que les résultats pour lesquels ils ont été conçus. Ils ne couvrent pas toutes les branches de votre intégration : vérifiez donc vos propres chemins d'erreur séparément.

Étape 2 : passez à une clé Live dotée des bonnes portées

En production, selon la référence API, il vous faut une clé Live avec la portée submit pour créer des tâches. Ajoutez la portée read pour lire l'état des tâches et les résultats. Les clés Live peuvent aussi disposer d'une portée balance. Le secret complet d'une clé ne s'affiche qu'une seule fois : stockez-le donc de manière sécurisée sur votre serveur dès sa création. Une clé révoquée bloque les nouvelles requêtes.

Les tâches Live utilisent la file de vérification et le solde de crédits de votre espace de travail. Les portées des clés, les plafonds des clés, les accès à l'espace de travail et les limites de traitement s'appliquent toujours. Une clé Live ne vous donne pas un accès illimité.

Étape 3 : divisez la liste et soumettez les tâches

Chaque tâche accepte de 1 à 5 000 adresses en JSON, dans la limite de 2 Mio. Voici une approche pratique :

1. Découpez votre liste. À titre d'exemple, 12 000 adresses donneraient trois tâches de 5 000, 5 000 et 2 000.
2. Attribuez à chaque segment sa propre Idempotency-Key stable, et notez quelles lignes de vos données ont été placées dans quel segment. Conserver cette correspondance de votre côté facilite le rattachement des résultats à vos enregistrements.
3. Soumettez au point de terminaison des tâches. Une nouvelle tâche renvoie HTTP 202 avec un job_id au format UUID. Une nouvelle tentative identique renvoie HTTP 200 avec la même tâche. Vous pouvez donc renvoyer la même requête avec la même clé après un délai d'expiration et récupérer la tâche existante.

Étape 4 : gérez les deux erreurs qui se ressemblent

Ces deux réponses peuvent bloquer une soumission, mais elles n'ont pas la même signification :

• HTTP 503 live_verification_unavailable peut être renvoyé pendant une pause opérationnelle. Selon la référence API, cela se produit sans qu'aucun crédit ne soit bloqué. Réessayez plus tard avec la même Idempotency-Key.
• HTTP 402 key_cap_reached signifie qu'une nouvelle requête dépasserait le plafond de dépenses à vie de la clé. Ce plafond comptabilise les crédits déjà débités ainsi que les crédits réservés pour les identités uniques acceptées. Aucune tâche ni aucune réservation n'est créée. Un plafond à vie ne se reconstitue pas avec le temps : attendre ne résoudra donc rien. Vérifiez le plafond de la clé dans les paramètres des clés API, ou utilisez une clé disposant d'un plafond restant suffisant pour le travail. Un plafond de clé ne peut pas non plus ajouter de crédits à l'espace de travail. Il limite seulement ce que cette clé peut dépenser.

Journalisez ces deux réponses séparément des erreurs d'autorisation et des limites de traitement, afin que la bonne personne reçoive la bonne alerte.

Étape 5 : suivez l'état des tâches, puis paginez les résultats

Le point de terminaison d'une tâche renvoie son état actuel et un récapitulatif. Le statut d'une tâche peut être : en file d'attente, en cours, en pause, en cours d'annulation, annulée ou terminée. Si vous demandez une annulation, le travail déjà en cours peut tout de même aboutir.

Le point de terminaison des résultats renvoie jusqu'à 50 résultats à la fois, accompagnés d'un next_cursor signé. Transmettez cette valeur dans le paramètre de requête cursor. Il conserve votre filtre et votre recherche d'origine. Les filtres disponibles sont all, valid, invalid, catch_all, unknown, still_checking et not_checked. Vous pouvez les utiliser pour ne récupérer que les lignes qui nécessitent une décision, par exemple tout ce qui est marqué unknown.

Étape 6 : transformez les verdicts en décisions

Le guide des résultats présente les résultats comme des indices, et non comme une garantie de délivrabilité :

• Valide indique une vérification positive exploitable. Cela ne garantit jamais la remise en boîte de réception.
• Invalide signifie que l'adresse n'a pas passé la vérification.
• Catch-all signifie que le domaine peut accepter de nombreuses adresses ; une conclusion sur la boîte aux lettres précise peut donc être moins certaine. Consultez le détail avant d'utiliser l'adresse.
• Inconnu signifie que la vérification n'a pas pu fournir de réponse fiable.
• Vérification en cours signifie qu'il n'y a pas encore de réponse définitive. Continuez à interroger l'API et ne traitez pas ce statut comme Inconnu.

Les échecs techniques et les éléments non traités constituent une catégorie distincte. Les règles relatives aux crédits de FairValid précisent qu'ils ne sont pas reclassés en Inconnu.

Étape 7 : comprenez la réservation des crédits

Selon la référence API, les crédits de l'espace de travail sont réservés à mesure que les vérifications sont admises au traitement. Les résultats suivent les mêmes règles de débit et de restitution que le tableau de bord. Selon les règles relatives aux crédits, un résultat Valide ou Invalide finalisé coûte un crédit. Les résultats Inconnu et Catch-all non résolus n'entraînent au final aucun débit de crédits, car les crédits réservés sont libérés ou restitués. « En attente » n'est pas un résultat définitif. Les échecs techniques et le travail non traité n'entraînent pas non plus de débit de crédits au final. Les crédits restitués conservent leur lot et leurs règles d'expiration d'origine.

Le point de terminaison du solde indique les crédits disponibles et réservés de l'espace de travail Live. Lorsque son champ free_allowance_held vaut true, l'allocation gratuite est suspendue et n'est comptabilisée ni dans available_credits ni dans free_available. Les crédits payants restent disponibles. Le compte d'origine reçoit 300 crédits gratuits chaque mois à sa date d'inscription, et les crédits gratuits non utilisés ne sont pas reportés. Les espaces de travail supplémentaires ne bénéficient pas d'une allocation gratuite additionnelle. Les crédits gratuits sont utilisés en premier, et les crédits payants n'expirent pas tant que le compte reste ouvert.

Une liste de contrôle simple

• Testez avec une clé de test et les cas de sandbox documentés.
• Utilisez une clé Live dotée des portées submit et read, avec un plafond adapté au travail prévu.
• Limitez chaque segment à 5 000 adresses au maximum, avec une clé d'idempotence stable par segment.
• Réessayez plus tard après une erreur 503, avec la même clé. N'attendez pas qu'une erreur 402 se résolve d'elle-même : agissez plutôt sur le plafond.
• Parcourez les résultats page par page avec le curseur signé, filtrés par verdict.
• Distinguez dans vos données les statuts en attente, les échecs techniques et les résultats Inconnu.

Si vous souhaitez essayer ce workflow, vous pouvez créer une clé de test et lancer une tâche dans le sandbox sans consommer de crédits avant votre première soumission Live. La référence API détaille l'ensemble des points de terminaison.