Référence de l’API REST Email Verifier

L’API Email Verifier est proposée sous /api/v1. Utilisez l’hôte TrekMail sur lequel votre compte se connecte. Les exemples utilisent https://YOUR-TREKMAIL-HOST comme valeur fictive.

Authentification et scopes

Transmettez un jeton API dans l’en-tête Authorization :

Authorization: Bearer YOUR_API_TOKEN

Activez les scopes lors de la création du jeton :

Accordez les deux scopes à un client qui doit soumettre une tâche, puis lire ou télécharger son résultat.

Hôte et format des requêtes

Tous les exemples emploient un corps JSON et un jeton Bearer. L’importateur de fichiers du tableau de bord est distinct de l’API : POST /verify/bulk accepte un tableau JSON emails, pas un fichier multipart. Utilisez exactement l’hôte associé au compte et au jeton. Ne supposez pas qu’un jeton ou un solde provenant d’un hôte de marque fonctionne sur un autre.

Envoyez Content-Type: application/json pour les requêtes POST /verify et POST /verify/bulk. Stockez le jeton et la valeur d’idempotence hors du code côté client.

Idempotence

POST /api/v1/verify/bulk et DELETE /api/v1/verify/bulk/{jobId} exigent l’en-tête Idempotency-Key. Générez une nouvelle valeur pour chaque opération prévue et réutilisez-la uniquement lorsque vous retentez cette même opération.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

La vérification individuelle et l’annulation d’une tâche n’exigent pas cet en-tête. Une requête groupée est également protégée par la détection des listes en double lorsque la même liste normalisée et le même mode sont utilisés sous 24 heures. La clé d’idempotence reste toutefois le bon mécanisme de nouvelle tentative.

Gérer un résultat réseau incertain

Si votre application perd la réponse d’une requête groupée, ne générez pas une nouvelle clé et ne soumettez pas une autre liste. Répétez la requête à l’identique avec la même clé. Stockez celle-ci avec l’identifiant de la liste source jusqu’à ce que TrekMail renvoie un ID de tâche. La nouvelle tentative reste ainsi liée à l’opération voulue au lieu de créer un second débit évitable.

Récapitulatif des endpoints

Ajoutez /api/v1 devant chaque chemin du tableau.

Lire le solde de crédits

GET /api/v1/verify/credits

Sur l’hôte TrekMail standard, la réponse inclut l’allocation du forfait et le solde acheté :

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

Sur un hôte White Label, seuls les crédits achetés sont disponibles pour le produit de marque. La réponse contient donc purchased_balance et total_available.

Exemple de requête :

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Lisez le solde juste avant une soumission importante. La réponse est un instantané. Une application qui soumet plusieurs tâches doit donc enregistrer le montant débité dans chaque réponse groupée au lieu de le recalculer plus tard à partir d’un chiffre périmé.

Champs du solde

Les réponses de solde White Label comportent volontairement moins de champs, car le produit de marque utilise uniquement les crédits achetés.

Vérifier une adresse

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

La réponse inclut email, status, trust_score, checks, provider, risk_factors et credits_remaining. Sur l’hôte standard, credits_remaining contient les valeurs monthly et purchased. La structure détaillée de checks peut varier selon le mode et les informations rendues disponibles par le fournisseur destinataire.

Quick coûte 1 crédit. Deep coûte normalement 2 crédits, tandis que les exceptions propres à certains fournisseurs sont facturées 1 crédit. Si la vérification ne peut pas s’exécuter après le débit, la requête individuelle rembourse ce débit et renvoie une réponse d’indisponibilité temporaire.

Exemple de requête :

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

Utilisez les champs de premier niveau status, trust_score, provider et risk_factors comme contrat normal de l’application. checks fournit des éléments utiles, mais ses clés peuvent varier lorsqu’un contrôle en amont est ignoré ou indisponible, ou lorsque Deep obtient des informations supplémentaires.

Interpréter un résultat individuel

Ne laissez pas une application considérer une réponse distante acceptée comme un contrôle de propriété ou d’autorisation. Gérez séparément les abonnements, désabonnements et préférences de contact.

Créer une tâche groupée

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

Les doublons sont normalisés avant le calcul du prix. Une nouvelle tâche créée avec succès renvoie 201 avec :

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe et skip expliquent le calcul du prix Deep. deep_savings est la différence avec une facturation de chaque adresse au plein tarif Deep. Une liste en double renvoie le job_id et le statut existants au lieu de démarrer une autre tâche.

Exemple de requête :

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

L’API vérifie la validité syntaxique des valeurs soumises avant d’accepter la tâche. Si toutes sont rejetées, elle renvoie 422 sans créer de tâche. Si certaines sont rejetées, la réponse réussie indique rejected_count et jusqu’à cinq valeurs dans rejected_sample. Cette petite sélection n’est pas un rapport complet de nettoyage. Conservez le résultat de validation de la source dans votre propre importateur.

Liste de contrôle d’une soumission groupée

1. Lisez et normalisez la source dans votre application.
2. Limitez la requête à 50,000 entrées soumises.
3. Générez et conservez une clé d’idempotence avant la requête.
4. Choisissez un nom de tâche assez clair pour qu’un opérateur puisse la reconnaître plus tard.
5. Stockez le job_id, les credits_charged et la ventilation tarifaire renvoyée par TrekMail.
6. Interrogez régulièrement le job_id stocké ; ne déduisez pas la fin de la requête HTTP initiale.

Lire une tâche

GET /api/v1/verify/bulk/{jobId}

La réponse de base inclut job_id, name, status, total, processed, progress, summary, created_at et completed_at.

Lorsque des résultats sont disponibles pour une tâche terminée, partielle ou en échec, la réponse inclut également :

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Paramètres de requête facultatifs :

Une tâche annulée comprenant des lignes traitées est téléchargeable, mais utilisez l’endpoint de téléchargement pour l’exporter.

Lire les états sans les deviner

Un client API doit effectuer ses interrogations avec temporisation progressive. Ne lancez pas une nouvelle soumission groupée uniquement parce que la tâche reste en attente ou qu’une requête réseau a expiré localement.

Exemple de réponse d’état

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary peut évoluer à mesure que le travail avance. Utilisez processed et total pour afficher la progression au lieu d’additionner uniquement les catégories que l’application reconnaît déjà.

Télécharger une tâche

GET /api/v1/verify/bulk/{jobId}/download

Le téléchargement est disponible pour les tâches terminées, partielles ou annulées qui comportent des lignes traitées. Il diffuse un CSV avec les colonnes Email, Status, Trust Score, Provider et Risk Factors.

Exemple :

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Enregistrez le fichier téléchargé pendant la période de conservation des résultats de 15 jours. Le CSV est destiné à votre propre processus ; il ne modifie ni le consentement, ni les abonnements, ni les contacts d’un autre système.

L’endpoint de téléchargement renvoie un conflit si aucun export traité n’est disponible. Vérifiez d’abord l’état de la tâche. Une requête réussie diffuse le CSV sans enveloppe JSON. Traitez-la donc comme une réponse de fichier dans votre client HTTP.

Répertorier les tâches

GET /api/v1/verify/bulk

Utilisez page, per_page et éventuellement status. per_page vaut 20 par défaut et accepte de 1 à 100. Les statuts sont pending, processing, completed, partial, cancelled et failed.

La réponse contient un tableau jobs et un objet pagination. Chaque tâche comporte son ID, son nom, son statut, son total, son nombre traité, sa progression et ses horodatages.

Exemple :

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Utilisez l’endpoint de liste après le redémarrage d’un worker ou pour rapprocher les ID de tâches. Un nom de tâche n’est pas un identifiant unique ; stockez le job_id numérique renvoyé.

Structure de la réponse de liste

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Utilisez le paramètre status lorsqu’une page d’exploitation ne nécessite que les tâches actives ou terminées. La pagination est importante pour les comptes qui vérifient beaucoup de listes ; ne supposez pas qu’une réponse contient tout l’historique.

Annuler une tâche

POST /api/v1/verify/bulk/{jobId}/cancel

Annulez uniquement les tâches en attente ou en cours. Une réponse réussie est :

{"status":"cancelled","credits_refunded":40}

Le remboursement porte sur le travail non traité. Si la tâche atteint un état final avant l’annulation, l’API renvoie un conflit au lieu de modifier son résultat.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

L’annulation ne supprime pas la tâche. Téléchargez les lignes traitées si nécessaire ou supprimez ensuite l’enregistrement terminé.

Supprimer une tâche

DELETE /api/v1/verify/bulk/{jobId}

Annulez d’abord une tâche en cours. La suppression retire définitivement la tâche et ses résultats après que TrekMail a supprimé de manière sécurisée la liste source préparée. Une réponse réussie est :

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Cette opération est définitive pour l’enregistrement du vérificateur. Elle ne retire pas les fichiers CSV déjà téléchargés par votre application. Appliquez votre propre politique de conservation à ces copies.

Ordre de suppression

1. Lisez le statut de la tâche.
2. Annulez-la si elle est en attente ou en cours de traitement.
3. Enregistrez tout export traité que vous devez conserver.
4. Supprimez avec une clé d’idempotence la tâche qui n’est plus en cours.
5. Supprimez les copies détenues par votre système selon ses règles de confidentialité et de conservation.

Erreurs et nouvelles tentatives

La vérification individuelle est limitée à 60 requêtes par minute sur sa route, et la soumission groupée à 10 requêtes par minute. Prévoyez des tentatives avec temporisation progressive, conservez la même clé pour retenter une requête groupée et ne réessayez pas aveuglément après un résultat réseau inconnu.

Modèle sûr de nouvelle tentative

1. Générez et conservez une clé d’idempotence avant une soumission groupée.
2. Envoyez la requête avec cette clé.
3. Si la réponse est perdue, répétez la même requête avec la même clé.
4. Conservez le job_id renvoyé et cessez de créer de nouvelles soumissions pour cette liste source.
5. Interrogez cette tâche jusqu’à son état final, puis téléchargez ou traitez son résultat.

Pour une vérification individuelle, un 503 temporaire signifie que le service n’a pas pu terminer le contrôle. Réessayez plus tard avec la temporisation habituelle. Ne transformez pas cette réponse en résultat Invalid dans votre base de données.

Protéger les données des contacts

Les listes d’adresses sont des données personnelles dans de nombreux contextes. Envoyez uniquement les données requises pour la vérification, limitez l’accès du jeton au système exécutant la tâche et évitez de journaliser les tableaux complets d’adresses. Si une journalisation est nécessaire, stockez l’ID de tâche, le nombre, le minutage et le résultat général, pas la liste complète.

TrekMail conserve les résultats pendant 15 jours. Prévoyez un stockage sécurisé des exports ou un processus de suppression avant d’intégrer des listes volumineuses.

Les signaux de vérification ne prouvent ni la propriété d’une personne, ni son consentement, ni la livraison future. Conservez la gestion des autorisations et des suppressions dans votre application, même lorsqu’une adresse obtient Safe.