Documentation

Les endpoints que vous appelez vraiment.

Une clé, deux endpoints : vérifier une adresse ou vérifier une liste.

01Authentification

Une clé, envoyée en bearer token.

Chaque requête porte votre clé API. Les clés se créent dans le tableau de bord et portent les scopes verify et bulk.

Authorization: Bearer bi_live_…
Content-Type: application/json

Une clé n'est affichée qu'à sa création ; nous n'en gardons que le préfixe. En cas de fuite, révoquez-la et créez-en une autre ; les autres continuent de fonctionner.

02Unitaire / temps réel

Vérifier une adresse.

Une vérification synchrone : syntaxe, DNS, MX, puis une conversation SMTP avec le serveur destinataire. Un crédit.

POSThttps://api.bounceintel.com/v1/check_email

Vérifier une adresse

Renvoie le rapport scoré complet. Latence médiane sous 500 ms ; prévoyez 30 s pour un serveur lent.

verify.sh

curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Réponse200

{
  "input": "[email protected]",
  "is_reachable": "safe",
  "provider": "google_workspace",
  "provider_confidence": "high",
  "score": {
    "score": 100,
    "category": "valid",
    "sub_reason": "deliverable",
    "safe_to_send": true,
    "confidence": 95,
    "confidence_level": "high",
    "reason_codes": ["provider_reputation"],
    "signals": {
      "valid_syntax": true,
      "has_mx_records": true,
      "smtp_can_connect": true,
      "smtp_is_deliverable": true,
      "smtp_is_catch_all": false
    }
  },
  "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
  "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
  "smtp": {
    "can_connect_smtp": true,
    "is_deliverable": true,
    "is_catch_all": false,
    "has_full_inbox": false,
    "is_disabled": false
  },
  "misc": { "is_disposable": false, "is_role_account": false, "is_b2c": false },
  "bounce_risk": { "score": 8, "category": "low", "action": "send", "confidence": 0.71 }
}

mx, smtp et misc sont des unions : soit l'objet de détail, soit un objet d'erreur si l'étape n'a pas abouti. Vérifiez le type avant de lire.

03En masse / asynchrone

Vérifier une liste.

Envoyez toute la liste en une requête, suivez la progression, puis paginez les résultats. Un crédit par adresse, débité à l'envoi.

POSThttps://api.bounceintel.com/v1/bulk

Envoyer une liste

Envoyez toutes les adresses en un appel. La réponse est un identifiant de job ; la vérification s'exécute en arrière-plan.

bulk.sh

curl -sS -X POST 'https://api.bounceintel.com/v1/bulk' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'

Réponse200

{
  "job_id": 8
}

Les crédits sont débités pour le lot entier à l'envoi, de façon atomique : deux jobs simultanés ne peuvent pas dépenser le même solde. Si le lot dépasse vos crédits restants, la requête entière est refusée ; rien n'est débité partiellement.

GEThttps://api.bounceintel.com/v1/bulk/{job_id}

Suivre la progression

Interrogez pendant l'exécution. finished_at reste null tant que toutes les adresses n'ont pas été traitées.

status.sh

curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"

Réponse200

{
  "job_id": 8,
  "created_at": "2026-09-02T15:16:15.447365Z",
  "finished_at": null,
  "total_records": 4,
  "total_processed": 2,
  "summary": {
    "total_safe": 1,
    "total_risky": 0,
    "total_invalid": 1,
    "total_unknown": 0
  },
  "job_status": "Running"
}

Interrogez toutes les quelques secondes, pas en boucle serrée. Les compteurs du résumé sont mis à jour en direct.

GEThttps://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0

Récupérer les résultats

Paginez les résultats terminés. Chaque ligne a la même forme qu'une vérification unitaire.

results.sh

curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"

Réponse200

{
  "results": [
    {
      "input": "[email protected]",
      "is_reachable": "safe",
      "provider": "google_workspace",
      "score": {
        "score": 100,
        "category": "valid",
        "safe_to_send": true,
        "sub_reason": "deliverable",
        "reason_codes": ["provider_reputation"]
      },
      "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
      "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
      "smtp": { "can_connect_smtp": true, "is_deliverable": true, "is_catch_all": false },
      "misc": { "is_disposable": false, "is_role_account": false },
      "bounce_risk": { "score": 8, "category": "low", "action": "send" }
    }
  ]
}

limit vaut 50 par défaut en JSON. Précisez-le, jusqu'à 1000, et paginez avec offset. Utilisez format=csv pour récupérer l'ensemble en fichier.

04Assistants IA

Vérifiez depuis votre assistant IA.

BounceIntel propose un serveur MCP à l'adresse https://api.bounceintel.com/mcp. Connectez Claude Code, Cursor, VS Code ou tout client compatible MCP sur HTTP : l'assistant vérifie des adresses et des listes pour vous, avec la même clé API et les mêmes crédits.

terminal

claude mcp add --transport http bounceintel https://api.bounceintel.com/mcp \
  --header "Authorization: Bearer $BOUNCEINTEL_KEY"

Envoyez votre clé API en bearer token, comme pour l'API REST. Les exemples la lisent depuis BOUNCEINTEL_KEY, pour qu'elle n'apparaisse pas dans des fichiers que vous pourriez versionner.

Outil	Scope de la clé	Ce qu'il fait
verify_email	verify	Vérifie une adresse et renvoie le verdict, le score et la raison. Un crédit.
verify_email_list	bulk	Lance une vérification en masse pour une liste et renvoie l'identifiant du job. Un crédit par adresse unique.
get_bulk_job	bulk	Indique l'avancement d'un job et le nombre d'adresses pour chaque verdict. Aucun crédit.
get_bulk_results	bulk	Renvoie les verdicts d'un job terminé, page par page, filtrés par verdict si besoin. Aucun crédit.
get_account	toute clé	Affiche le forfait, les crédits restants et la date de renouvellement. Aucun crédit.

Les jobs en masse tournent en arrière-plan : l'assistant lance le job, suit son avancement, puis lit les résultats. Les outils qu'une clé n'a pas le droit d'utiliser sont masqués pour l'assistant.

05Erreurs

Ce qui peut revenir.

Chaque échec renvoie un JSON avec un champ error. Voici ceux à traiter.

Statut	Erreur	Que faire
400	invalid_request	Corps mal formé ou adresse inexploitable. Corrigez et renvoyez.
401	unauthorized	Clé absente, incorrecte ou révoquée.
403	forbidden	Clé valide mais sans le scope requis.
429	rate_limited	Trop de requêtes. Attendez puis réessayez.
429	quota_exceeded	Plus de crédits. Seul un achat débloque la situation ; réessayer ne sert à rien.
503	unavailable	Impossible d'établir votre quota. Transitoire : réessayez sous peu.

06Bac à sable

Essayez avec votre clé.

Lance une vraie vérification sur votre compte. Un crédit pour une adresse ; un par adresse en bulk, débité à la soumission.

Collez votre propre clé d'API pour essayer. La clé est transmise à notre backend, utilisée une fois, et n'est pas conservée. Les contrôles invités n'utilisent pas votre clé.

URL de base : https://api.bounceintel.com

POST https://api.bounceintel.com/v1/check_email

Clé API

verify.sh

curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Les extraits copiés utilisent $BOUNCEINTEL_KEY, jamais la clé saisie.