Démarrage rapide avec l’API de TrekMail Email Verifier

Utilisez l’API lorsque la vérification doit faire partie de votre produit ou de votre flux d’importation. Créez un jeton avec verify:read et verify:write, gardez-le secret et appelez le même hôte que celui utilisé pour vous connecter. Dans les exemples, remplacez https://YOUR-TREKMAIL-HOST et YOUR_API_TOKEN.

1. Créer un jeton

1. Ouvrez Dashboard → AI Agents & API.
2. Créez un jeton.
3. Activez verify:read et verify:write.
4. Stockez le jeton de manière sécurisée. Il ne s’affiche qu’une fois.

Envoyez-le avec chaque requête :

Authorization: Bearer YOUR_API_TOKEN

Conservez le jeton dans un coffre à secrets ou une variable d’environnement. Ne l’insérez pas dans du code exécuté par le navigateur, un dépôt public, une demande d’assistance ou un fichier de contacts exporté. Si vous pensez qu’il a été exposé, révoquez-le et créez-en un autre dans le dashboard.

2. Vérifier une adresse

Utilisez POST /api/v1/verify pour obtenir immédiatement le résultat d’une seule adresse. Quick est la valeur par défaut lorsque mode est omis.

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"}'

La réponse contient des champs de premier niveau stables, comme l’adresse, le statut, le score de confiance, le fournisseur, les facteurs de risque et les crédits restants. L’objet checks consigne les éléments détaillés et peut varier lorsqu’un contrôle est indisponible ou que le mode Deep fournit des informations supplémentaires.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Lisez d’abord status et trust_score. Considérez les clés de chaque contrôle comme des précisions complémentaires, pas comme une garantie de propriété de la boîte ou de livraison.

Le point de terminaison individuel est limité à 60 requêtes par minute pour cette route. Si vous contrôlez une adresse saisie lors de l’inscription, appelez-le après une validation de base côté client et affichez une erreur simple si le service est temporairement indisponible, au lieu de bloquer indéfiniment la personne.

3. Soumettre un traitement groupé

Les requêtes groupées acceptent un tableau JSON emails, pas le chargement d’un fichier. Incluez une clé d’idempotence afin qu’une nouvelle tentative réseau ne crée pas un second traitement.

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

La liste peut contenir jusqu’à 50,000 entrées. TrekMail normalise les doublons et écarte du traitement les entrées dont la syntaxe est incorrecte. La réponse indique l’ID du traitement, le nombre accepté, un petit échantillon rejeté, les crédits facturés et le détail du tarif Deep.

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

probe est le nombre facturé au tarif Deep complet. skip est le nombre facturé au tarif normal, car le fournisseur ne donne pas d’éléments utiles au niveau de la boîte. La réponse constitue le coût de référence pour cette soumission.

Avant de soumettre une liste complète, retirez les valeurs qui ne sont pas des adresses dans votre propre outil d’importation. L’API déduplique les adresses et indique le nombre rejeté, mais la validation à la source crée une piste d’audit plus claire. Si la requête expire du point de vue de votre application, relancez la même requête groupée avec la même clé d’idempotence et vérifiez l’ID renvoyé avant toute nouvelle soumission.

4. Suivre et télécharger

Interrogez le traitement avec GET /api/v1/verify/bulk/{jobId} jusqu’à ce qu’il atteigne un état final :

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

La réponse comprend status, total, processed, progress, summary, l’heure de création et l’heure d’achèvement. Les traitements terminés et partiels comprennent un tableau results paginé.

Interrogez le service à un intervalle raisonnable avec une temporisation progressive. Un traitement peut rester en attente avant le début du travail, et Deep peut prendre plus de temps lorsqu’un fournisseur destinataire apporte des éléments supplémentaires. Ne déduisez pas une durée d’achèvement fixe de la seule taille de la liste.

Vous pouvez demander une page de résultats plus petite ou rechercher une adresse connue une fois les résultats disponibles :

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Téléchargez un traitement effectué au format CSV :

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

Les filtres d’exportation de l’API sont all, safe et safe_risky (Safe + Valid + Risky).

Pour arrêter un traitement en attente ou en cours, utilisez le point de terminaison d’annulation. Il rembourse le travail non traité et conserve les lignes déjà traitées :

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

Ne supprimez un traitement que si vous souhaitez retirer son enregistrement du vérificateur ainsi que ses résultats. S’il est encore en cours, annulez-le d’abord, puis utilisez le point de terminaison de suppression avec une clé d’idempotence. La référence complète présente les deux appels.

5. Gérer les réponses habituelles

• 402 : le compte a besoin de crédits supplémentaires.
• 422 : vérifiez le corps de la requête, le mode sélectionné ou la clé d’idempotence obligatoire pour une requête groupée.
• 429 : ralentissez et réessayez avec une temporisation progressive.
• 503 : la vérification est temporairement indisponible. Réessayez plus tard ; une vérification individuelle ayant échoué est remboursée.

Liste de contrôle pour une intégration en production

1. Conservez le jeton côté serveur et n’accordez que les deux portées nécessaires au vérificateur.
2. Validez et normalisez les contacts avant d’appeler l’API groupée.
3. Stockez l’ID du traitement, l’identifiant de la liste soumise, la clé d’idempotence et la valeur credits_charged renvoyée.
4. Interrogez avec une temporisation progressive plutôt qu’en boucle serrée.
5. Stockez ou traitez le CSV avant la fin de sa période de conservation de 15 jours.
6. Gérez le consentement, les désinscriptions et les décisions de suppression dans votre propre application. Un résultat du vérificateur ne les remplace pas.

Consultez la Référence de l’API REST Email Verifier pour tous les points de terminaison, portées et champs de réponse.