Workflow de validation d'e-mails par API : du sandbox à la production avec FairValid

Workflow de validation d'e-mails par API : du test en sandbox aux résultats en production

Question : Vous êtes développeur et vous ajoutez la vérification d'e-mails à votre propre système. Quelles étapes vous mènent d'un premier appel de test à des résultats fiables en production ?

Réponse courte : Commencez avec une clé Test et le sandbox gratuit. Passez ensuite à une clé Live disposant uniquement des portées nécessaires. Envoyez chaque soumission avec une clé d'idempotence. Lisez l'état du job et parcourez les résultats page par page. Traitez chaque résultat et chaque code d'erreur séparément. Les étapes ci-dessous suivent la référence API client de FairValid.

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

Créez une clé Test sur la page des clés API et conservez-la sur votre serveur. La référence utilise deux variables d'environnement, FAIRVALID_API_KEY et FAIRVALID_BASE_URL. Les clés Test n'appellent aucun fournisseur et ne consomment aucun crédit.

Les clés Test n'acceptent qu'un petit ensemble d'adresses réservées sur le domaine example.com. Ces adresses simulent des résultats valides, invalides, catch-all, inconnus, en attente et indisponibles. Vous trouverez les adresses exactes dans la section « Sandbox gratuit » de la référence API. Les jobs de test renvoient des états fixes et reproductibles : terminé, en attente, échoué ou annulé. Les jobs de test en masse prennent en charge le statut, les résultats et l'annulation.

Le sandbox vous montre ces résultats précis. Il ne couvre pas tous les chemins que votre intégration peut emprunter : prévoyez donc un traitement distinct pour les codes d'erreur décrits à l'étape 7.

Les jobs de test en masse sont limités à 20 nouveaux jobs par espace de travail et par heure, ou 100 sur 30 jours. Le dépassement de l'une ou l'autre limite renvoie HTTP 429. Une nouvelle tentative identique renvoie toujours le job d'origine.

Étape 2 : passez à une clé Live avec les portées nécessaires

Pour la production, créez une clé Live avec la portée submit. Utilisez POST /api/v1/jobs pour les lots ou POST /api/v1/verifications pour une adresse unique. Ajoutez la portée read si la clé doit aussi lire l'état des jobs et les résultats. Les clés Live peuvent également disposer d'une portée balance. Par ailleurs, GET /api/v1/balance lit les crédits disponibles et réservés de l'espace de travail. Le secret complet n'est affiché qu'une seule fois : conservez-le en lieu sûr lors de la création de la clé.

Les jobs 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 continuent de s'appliquer.

Étape 3 : soumettez un job avec une clé d'idempotence

Un job accepte de 1 à 5 000 adresses en JSON, jusqu'à 2 Mio. Envoyez un en-tête Idempotency-Key avec chaque soumission de job et chaque soumission Live d'adresse unique. La clé doit comporter de 8 à 128 caractères et peut contenir des lettres, des chiffres, des points, des deux-points, des tirets bas ou des traits d'union.

• Un nouveau job renvoie HTTP 202 avec un job_id au format UUID.
• Une nouvelle tentative identique renvoie HTTP 200 avec le même job.
• Réutiliser une clé d'idempotence avec un corps modifié renvoie HTTP 409 idempotency_conflict.

Si vous ne savez pas si une requête a abouti, réessayez avec la même clé API, la même clé d'idempotence et le même corps normalisé. La relecture est limitée à la clé API : remplacer cet identifiant et soumettre à nouveau peut donc créer une seconde exécution. N'utilisez une nouvelle clé d'idempotence que si vous souhaitez réellement une nouvelle exécution, qui peut être facturée.

Étape 4 : lisez le job et parcourez les résultats

Lisez le job avec GET /api/v1/jobs/{id}. Son statut peut être en file d'attente, en cours, en pause, en cours d'annulation, annulé ou terminé. Lisez les résultats avec GET /api/v1/jobs/{id}/results. Chaque page renvoie jusqu'à 50 résultats ainsi qu'un next_cursor signé. Transmettez cette valeur dans le paramètre de requête cursor. Elle conserve votre filtre et votre recherche d'origine.

Les filtres sont all, valid, invalid, catch_all, unknown, still_checking et not_checked. Pour arrêter un job, POST /api/v1/jobs/{id}/cancel demande l'annulation, mais le travail déjà en cours peut tout de même se terminer.

La référence décrit également un événement de fin signé et renvoie vers la gestion des webhooks.

Étape 5 : traitez chaque résultat comme un état à part entière

Le guide des résultats explique la signification de chaque résultat :

• Valide : une vérification positive exploitable. Elle ne garantit jamais la remise en boîte de réception.
• Invalide : l'adresse n'a pas passé la vérification.
• Catch-all : le domaine peut accepter de nombreuses adresses, de sorte qu'une conclusion au niveau de la boîte aux lettres peut être moins certaine. Lisez le détail avant de l'utiliser.
• Inconnu : la vérification n'a pas pu fournir de réponse fiable.
• Vérification en cours : il n'y a pas encore de réponse définitive.

Le guide décrit les échecs techniques et les éléments non traités séparément du statut Inconnu, et l'API propose unknown, still_checking et not_checked comme filtres distincts. Conservez ces états dans des champs ou statuts distincts dans vos propres données plutôt que de les fusionner dans Inconnu.

Étape 6 : comprenez les réservations de crédits avant le rapprochement

La référence API indique que 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 ensuite les mêmes règles de débit et de restitution que le tableau de bord. La tarification de FairValid précise qu'une réservation de crédits garde de la place pour une vérification en cours, et que le résultat final détermine le débit :

• Valide ou invalide : 1 crédit par résultat obtenu.
• Inconnu ou catch-all : aucun crédit de vérification n'est finalement débité. Les crédits réservés sont libérés ou restitués.
• Vérification en cours : aucun débit définitif pour l'instant. Une réservation n'est pas un débit finalisé.
• Échecs techniques et travail non traité : aucun crédit de vérification n'est finalement débité. Les réservations sont libérées ou restituées.

Si vous consultez votre solde en cours de job, gardez à l'esprit que les crédits réservés ne sont pas encore des débits définitifs. Effectuez le rapprochement une fois les résultats définitifs. Chaque compte inclut 300 crédits gratuits par mois. Ils sont utilisés en premier et ne sont pas reportés. Les crédits payants non utilisés restent disponibles tant que le compte est ouvert.

Étape 7 : traitez les erreurs selon leur cause, pas avec une règle de nouvelle tentative unique

• 401 : la clé est absente, révoquée ou ne dispose pas de la portée requise. Corrigez l'identifiant ou ses portées.
• 402 key_cap_reached : la nouvelle requête dépasserait le plafond à vie de la clé, et aucun job ni aucune réservation n'a été créé. Le 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. Comme il s'agit d'une limite à vie, elle ne se renouvelle pas avec le temps, et attendre ne la lèvera pas. Demandez à une personne disposant des droits d'accès de revoir le paramètre de plafond de cette clé. Un plafond ne peut pas ajouter de crédits à l'espace de travail.
• 422 : adresses invalides ou limites de liste. Corrigez les données envoyées.
• 503 live_verification_unavailable : pendant une pause opérationnelle, une nouvelle soumission Live peut renvoyer cette erreur sans réserver de crédits. Réessayez plus tard avec la même clé d'idempotence. Une erreur 503 après une soumission incertaine ne prouve pas qu'aucun job n'a été créé : réutilisez donc la clé d'origine.

Chaque erreur comprend un code, un message et un identifiant de requête. Journalisez les trois afin de les avoir sous la main si vous contactez le support.

Un ordre de travail raisonnable

1. Développez l'intégration avec le sandbox et vérifiez que chaque résultat simulé aboutit là où vous l'attendez.
2. Ajoutez un traitement explicite pour les codes d'erreur ci-dessus.
3. Créez une clé Live avec les portées les plus restreintes possibles et un plafond adapté à votre budget.
4. Commencez par un petit job Live. Comparez ses résultats et l'état des crédits avec le tableau de bord, puis augmentez le volume.

Si vous souhaitez essayer ce workflow, le sandbox gratuit vous permet de tester les résultats simulés sans consommer de crédits. La référence API contient le détail exact des requêtes.