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/verify | Vérifier une adresse unique : réponse immédiate. |
| POST | /api/v1/lists | Créer une liste en masse à partir d'un tableau JSON. |
| GET | /api/v1/lists/:id | Récupérer le statut d'une liste. |
| GET | /api/v1/lists/:id/results | Récupérer les résultats d'une liste. |
| DELETE | /api/v1/lists/:id | Supprimer définitivement une liste (RGPD). |
| GET | /api/v1/credits | Récupérer le solde de crédits restant. |
| POST / GET / DELETE | /api/v1/webhooks | Enregistrer, 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.
| unauthorized | 401 | Clé manquante ou invalide. |
| forbidden | 403 | La clé n'est pas autorisée pour cette action (ex. une clé publiable interrogeant le solde). |
| not_found | 404 | L'enregistrement n'existe pas ou ne vous appartient pas. Dans les deux cas la réponse est 404, jamais 403. |
| invalid_request | 400 | Le corps ne correspond pas au schéma attendu. |
| insufficient_credits | 402 | Solde de crédits insuffisant. |
| rate_limited | 429 | Limite de requêtes dépassée. Attendez la durée indiquée dans l'en-tête Retry-After. |
| too_large | 413 | La taille du corps dépasse la limite. |
| internal | 500 | Erreur 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).