Documentation API

API REST publique : authentification, points de terminaison, dictionnaire d'erreurs, clé sandbox.

Authentification

Envoyez l'en-tête Authorization: Bearer <clé> avec chaque requête. Vous générez les clés depuis votre session connectée (Paramètres → Clés API). L'API elle-même n'en crée jamais, donc une clé volée ne peut pas en créer d'autres.

curl https://your-domain.com/api/v1/verify \
  -H "Authorization: Bearer cl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

Clé sandbox

Une clé commençant par cl_test_ n'atteint jamais le worker et ne touche jamais aux crédits. Envoyez les adresses de test pour essayer chaque statut : ok@sandbox.test, invalid@sandbox.test, catch_all@sandbox.test, disposable@sandbox.test, role@sandbox.test, unknown@sandbox.test. Toute autre adresse renvoie unknown : une clé de test oubliée en production n'approuve jamais une vraie adresse.

Points de terminaison

Sept points de terminaison, tous hors du préfixe [locale], comme cette page :

POST/api/v1/verifyVérifier une adresse unique : réponse immédiate.
POST/api/v1/listsCréer une liste en masse à partir d'un tableau JSON.
GET/api/v1/lists/:idRécupérer le statut d'une liste.
GET/api/v1/lists/:id/resultsRécupérer les résultats d'une liste.
DELETE/api/v1/lists/:idSupprimer définitivement une liste (RGPD).
GET/api/v1/creditsRécupérer le solde de crédits restant.
POST / GET / DELETE/api/v1/webhooksEnregistrer, lister ou supprimer un point de terminaison webhook.

Dictionnaire d'erreurs

Chaque erreur a le même format : { error: { code, message, request_id } }. Le code est l'une des valeurs ci-dessous.

unauthorized401Clé manquante ou invalide.
forbidden403La clé n'est pas autorisée pour cette action (ex. une clé publiable interrogeant le solde).
not_found404L'enregistrement n'existe pas ou ne vous appartient pas. Dans les deux cas la réponse est 404, jamais 403.
invalid_request400Le corps ne correspond pas au schéma attendu.
insufficient_credits402Solde de crédits insuffisant.
rate_limited429Limite de requêtes dépassée. Attendez la durée indiquée dans l'en-tête Retry-After.
too_large413La taille du corps dépasse la limite.
internal500Erreur serveur, réessayez.

Idempotence

Envoyez un en-tête Idempotency-Key : une deuxième requête avec la même clé renvoie la première réponse réussie telle quelle. Les erreurs ne sont pas stockées : après un 4xx ou un 5xx, la même clé relance la requête. La même clé avec un corps différent renvoie 400. Si la première requête est encore en cours, une deuxième reçoit 429 avec Retry-After: 1 ; réessayez et vous obtenez la première réponse. La réponse stockée ne contient jamais d'adresse e-mail.

Limite de requêtes

Actuellement 60 requêtes par minute et par clé, sur une fenêtre glissante de 60 secondes. Au-delà, vous recevez un 429 avec un en-tête Retry-After.

Une clé publishable (navigateur) lance en outre au plus 500 vérifications par 24 heures par défaut ; vous modifiez cette valeur sur l'écran des clés API. Au-delà, les requêtes reçoivent un 429 et ne coûtent aucun crédit.

Intégrations prêtes à l'emploi

Avant d'appeler l'API directement, regardez ceci :

  • Synchronisation Mailchimp : récupérer une liste, la vérifier, réécrire les étiquettes (Paramètres → Intégrations).
  • Webhook : un POST signé à la fin d'une tâche groupée (X-Clearlist-Signature).
Documentation de l'API de vérification d'e-mails