API

Une API REST en HTTPS. Tout est en JSON, chaque champ est en snake_case, et la base est https://listcheckup.com. Aucun SDK à installer et rien à attendre — créez une clé et les deux commandes ci-dessous fonctionnent.

Authentification

Chaque requête porte une clé API, créée dans votre tableau de bord. Les clés commencent par lck_live_, peuvent recevoir une date d’expiration et sont révocables à tout moment.

curl "https://listcheckup.com/v1/me" \
  -H "Authorization: Bearer lck_live_..."

GET /v1/me répond avec le compte auquel la clé appartient et son solde, ce qui en fait le moyen le plus rapide de confirmer qu’une clé fonctionne :

{ "email": "[email protected]", "credits": 24600 }

Sans clé, ou avec une clé révoquée ou expirée, chaque endpoint répond 401 et précise lequel de ces cas s’applique — une clé révoquée et une faute de frappe appellent des corrections différentes.

Limite de requêtes

120 requêtes pour commencer, réapprovisionnées à 60 par minute, par clé. C’est un plafond sur le volume de requêtes et non sur les adresses : une liste d’un demi-million d’adresses ne fait qu’une requête. La dépasser renvoie 429, et il suffit d’attendre.

Vérifier une adresse

La réponse arrive directement. À utiliser quand quelqu’un attend — un formulaire d’inscription, un tunnel de commande — plutôt que pour une liste que vous détenez déjà.

curl "https://listcheckup.com/v1/[email protected]" \
  -H "Authorization: Bearer lck_live_..."

Il existe aussi un POST /v1/verify avec { "email": "..." } dans le corps, si une chaîne de requête est peu commode. Les deux renvoient la même chose :

{
  "email": "[email protected]",
  "normalized_email": "[email protected]",
  "local_part": "someone",
  "domain": "example.com",
  "status": "valid",
  "reason": "mailbox_accepted",
  "confidence": 95,
  "duration_ms": 412
}

status prend l’une de cinq valeurs, et confidence indique de 0–100 à quel point ce statut est fiable. Un catch-all obtient un score bas alors même que le serveur a accepté l’adresse, parce que l’acceptation n’y prouve rien.

status	Signification
valid	La boîte aux lettres existe et peut recevoir du courrier.
invalid	Elle ne peut pas recevoir de courrier. Retirez-la.
risky	Elle fonctionne, mais c’est une adresse jetable ou une boîte partagée plutôt qu’une personne.
catch_all	Le domaine accepte toutes les adresses, donc personne ne peut dire si celle-ci existe.
unknown	Le serveur de messagerie n’a pas voulu répondre. Un fait sur sa politique, pas sur l’adresse.

Vous ne payez que pour une réponse. catch_all et unknown ne coûtent rien : le travail a été fait et le serveur de messagerie a refusé de se prononcer — les facturer reviendrait à vous facturer notre incapacité à savoir.

Vérifier une liste

Quatre appels : créer, lancer, surveiller, récupérer.

1. Créer

Les adresses en JSON, pas en fichier — vous les détenez déjà sous forme de chaînes, et construire un corps multipart pour envoyer des chaînes serait du travail pour rien.

curl -X POST "https://listcheckup.com/v1/lists" \
  -H "Authorization: Bearer lck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "march-subscribers", "emails": ["[email protected]", "[email protected]"]}'

Rien n’est encore débité. La réponse est un récapitulatif de liste avec le prix, pour que vous puissiez décider avant de dépenser quoi que ce soit :

{
  "id": "7f3c1d20-9a4b-4c8e-8f21-5b6d7e8a9c04",
  "name": "march-subscribers",
  "status": "awaiting_confirmation",
  "addresses": 24600,
  "duplicates": 1020,
  "not_addresses": 180,
  "unique": 23580,
  "excluded": 0,
  "price": 23400,
  "checked": 0,
  "credits_charged": 0,
  "failure_reason": null,
  "created_at": "2026-03-18T09:12:00+00:00",
  "completed_at": null
}

price est exprimé en crédits et correspond à ce que coûtera le lancement. Les doublons ne sont comptés qu’une fois et les lignes qui ne sont pas des adresses ne sont jamais facturées : voilà pourquoi ce chiffre est inférieur à addresses.

2. Lancer

curl -X POST "https://listcheckup.com/v1/lists/<id>/start" \
  -H "Authorization: Bearer lck_live_..."

C’est l’appel qui dépense des crédits. 402 signifie que le solde est insuffisant, et que rien n’a été débité ni lancé.

3. Savoir quand c’est terminé

Enregistrez un webhook et nous envoyons un POST à votre serveur à l’instant où une liste se termine — signé, réessayé si votre côté est indisponible. C’est la bonne manière de faire.

Si vous préférez demander, GET /v1/lists/<id> renvoie le même récapitulatif que ci-dessus, avec status et checked qui avancent. Interrogez-le avec parcimonie ; un webhook ne vous coûte aucune requête.

status	Signification
uploaded	Acceptée, pas encore lue.
reading	En cours de comptage. price reste null jusqu’à la fin de cette étape.
awaiting_confirmation	Comptée et chiffrée. Rien n’est débité tant que vous ne l’avez pas lancée.
queued	Lancée, en attente d’un worker.
running	En cours. checked augmente.
completed	Terminée. Les résultats sont prêts.
failed	Arrêtée. Voir failure_reason.
cancelled	Arrêtée par vous. Les crédits non utilisés sont restitués.

4. Récupérer les résultats

curl "https://listcheckup.com/v1/lists/<id>/results?limit=500&skip=0" \
  -H "Authorization: Bearer lck_live_..."

limit vaut 500 par défaut et est plafonné à 2 000 ; paginez avec skip. Ajoutez include=valid,risky pour vous limiter aux catégories qui vous intéressent.

{
  "id": "7f3c1d20-...",
  "status": "completed",
  "total": 24600,
  "offset": 0,
  "returned": 500,
  "results": [
    {
      "row": 1,
      "email": "[email protected]",
      "status": "valid",
      "confidence": 95,
      "reason": "mailbox_accepted",
      "billable": true,
      "duplicate_of_row": null
    }
  ]
}

row est la position dans la liste que vous avez soumise : les résultats s’alignent donc sur vos propres enregistrements sans avoir à faire la correspondance sur l’adresse.

Supprimer

DELETE /v1/lists/<id> supprime une liste et ses résultats. Tout ce qui n’a pas été dépensé sur une liste jamais lancée revient.

Webhooks

Ajoutez un endpoint dans le tableau de bord et nous envoyons un POST signé dès qu’une liste se termine :

{
  "event": "list.finished",
  "occurred_at": "2026-03-18T09:41:00+00:00",
  "list": {
    "id": "7f3c1d20-...",
    "name": "march-subscribers",
    "checked": 24600,
    "safe_to_send": 12000,
    "to_remove": 7400,
    "uncertain": 3100
  }
}

Répondez par n’importe quel 2xx. Pour tout le reste, nous réessayons, six fois réparties sur environ une journée. Chaque requête porte une signature HMAC-SHA256 que vous vérifiez avec votre secret de signature ; le schéma exact, avec un exemple calculé, s’affiche à côté du secret au moment où vous créez l’endpoint.

Slack fonctionne sans rien de tout cela. Collez une URL de webhook entrant Slack à la place de la vôtre, et nous envoyons un message que Slack sait afficher plutôt que le JSON ci-dessus — rien à écrire, rien à héberger. Les nouvelles tentatives et le journal de livraison fonctionnent de la même façon.

L’utiliser depuis un assistant IA

Il existe un serveur MCP à l’adresse https://listcheckup.com/mcp. Pointez vers cette URL un assistant compatible MCP — Claude, ou un éditeur comme Cursor — avec la même clé API, et il pourra vérifier des adresses pour vous sans que personne écrive de code.

Se connecter

Quelle que soit la façon dont vous vous connectez, la clé voyage toujours de la même manière : dans un en-tête Authorization: Bearer <key>. Seul l’endroit où vous l’écrivez change.

Claude Code — une seule commande :

claude mcp add --transport http listcheckup https://listcheckup.com/mcp \
  --header "Authorization: Bearer lck_live_..."

Claude Desktop, Cursor et la plupart des autres clients — dans le fichier de configuration :

{
  "mcpServers": {
    "listcheckup": {
      "url": "https://listcheckup.com/mcp",
      "headers": { "Authorization": "Bearer lck_live_..." }
    }
  }
}

Vérifier que la connexion tient

Avant de le brancher à quoi que ce soit, demandez au serveur ce qu’il sait faire :

curl -X POST "https://listcheckup.com/mcp"   -H "Authorization: Bearer lck_live_..."   -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Six outils listés, vous êtes connecté. "error": "unauthorized" signifie que la clé n’est pas arrivée — presque toujours le mot Bearer et son espace qui manquent, ou la clé tronquée au moment du collage. Une clé fait une cinquantaine de caractères et commence par lck_live_.

Ce qu’il sait faire

Outil	Ce qu’il fait
check_email	Une adresse. Coûte un crédit, sauf si la réponse est catch-all ou unknown.
get_balance	Crédits restants. Gratuit.
create_list	Soumettre une liste et obtenir un prix. Ne débite rien.
start_list	Commencer la vérification. C’est l’appel qui dépense des crédits.
get_list	Statut et progression. Gratuit.
get_list_summary	Les chiffres une fois la liste terminée. Gratuit.

Le chiffrage et le lancement sont deux outils distincts à dessein : un assistant doit vous montrer ce que coûtera une liste avant que rien ne soit dépensé, et vous pouvez dire non. Aucun outil ne prend un compte en argument — c’est la clé dans l’en-tête qui décide de quels crédits sont utilisés, si bien que rien de ce qu’un assistant lit ou s’entend dire ne peut le diriger vers le compte de quelqu’un d’autre.

Traitez la clé comme un mot de passe

Tout ce qui la détient peut dépenser vos crédits. Elle se trouve en clair dans un fichier de configuration : gardez donc ce fichier hors d’un dépôt partagé, et révoquez la clé si elle se retrouve là où elle ne devrait pas — la révocation prend effet immédiatement, pour l’API comme pour ce serveur. Donnez à chaque machine sa propre clé et vous pourrez en révoquer une sans déranger les autres.

Erreurs

Chaque erreur est un JSON avec un code stable et une phrase destinée à un humain :

{ "error": "unauthorized", "message": "Provide your API key as 'Authorization: Bearer <key>'." }

Code	Signification
400	Quelque chose manque ou est incorrect dans la requête. Le corps dit quoi.
401	Pas de clé, ou une clé inconnue, révoquée ou expirée.
402	Crédits insuffisants. Rien n’a été débité ni lancé.
404	Cette liste n’existe pas sur ce compte.
409	La liste n’est pas dans un état où cela a un sens — déjà lancée, par exemple.
429	Limite de requêtes atteinte. Attendez.

Ce qu’elle ne fait pas

L’API vérifie des adresses que vous détenez déjà. Elle ne trouve, ne génère et ne fournit aucune adresse, et elle n’envoie jamais de courrier aux adresses qu’elle vérifie — la conversation avec chaque serveur de messagerie se termine avant qu’un message existe. L’utiliser sur des listes collectées par scraping, achetées ou louées est interdit ; voir utilisation acceptable.