API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

L'API EmailVerify est un service RESTful qui fournit de puissantes capacités de vérification d'emails. Toutes les requêtes API doivent être effectuées via HTTPS.

URL de Base

https://api.emailverify.ai/v1

Authentification

Toutes les requêtes API nécessitent une authentification utilisant un jeton Bearer dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY

Obtenez votre clé API depuis le tableau de bord EmailVerify.

Exemple

curl -X POST https://api.emailverify.ai/v1/verify \
  -H "Authorization: Bearer bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Limites de Taux

Plan	Requêtes/Heure	Requêtes/Jour
Gratuit	100	1 000
Débutant	1 000	10 000
Professionnel	10 000	100 000
Entreprise	Personnalisé	Personnalisé

Les informations de limite de taux sont incluses dans les en-têtes de réponse :

En-tête	Description
`X-RateLimit-Limit`	Nombre maximum de requêtes autorisées
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre
`X-RateLimit-Reset`	Horodatage Unix de réinitialisation de la limite

Lorsque la limite de taux est atteinte, vous recevrez une réponse 429 Too Many Requests :

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Points de Terminaison

Vérification d'Email Unique

Vérifiez une seule adresse email avec des résultats détaillés.

POST /verify

Requête

{
  "email": "user@example.com",
  "smtp_check": true,
  "timeout": 5000
}

Paramètres

Paramètre	Type	Requis	Défaut	Description
`email`	string	Oui	-	Adresse email à vérifier
`smtp_check`	boolean	Non	`true`	Effectuer une vérification de boîte aux lettres SMTP
`timeout`	integer	Non	`5000`	Délai d'expiration de la requête en millisecondes (max : 30000)

Réponse

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

Champs de Réponse

Champ	Type	Description
`email`	string	L'adresse email vérifiée
`status`	string	Statut de vérification : `valid`, `invalid`, `unknown`, `accept_all`
`result`	object	Résultats de vérification détaillés
`score`	number	Score de confiance (0.0 - 1.0)
`reason`	string	Raison du statut invalide/inconnu (nullable)
`credits_used`	integer	Nombre de crédits consommés

Champs de l'Objet Result

Champ	Type	Description
`deliverable`	boolean	Indique si l'email peut recevoir des messages
`valid_format`	boolean	Indique si l'email a une syntaxe valide
`valid_domain`	boolean	Indique si le domaine existe
`valid_mx`	boolean	Indique si le domaine a des enregistrements MX
`disposable`	boolean	Indique si l'email provient d'un service jetable
`role`	boolean	Indique si l'email est basé sur un rôle (info@, support@)
`catchall`	boolean	Indique si le domaine accepte tous les emails
`free`	boolean	Indique si l'email provient d'un fournisseur gratuit
`smtp_valid`	boolean	Indique si la vérification SMTP a réussi

Vérification d'Emails en Masse

Soumettez plusieurs adresses email pour vérification. Renvoie un ID de tâche pour suivre la progression.

POST /verify/bulk

Requête

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "smtp_check": true,
  "webhook_url": "https://your-app.com/webhooks/emailverify"
}

Paramètres

Paramètre	Type	Requis	Défaut	Description
`emails`	array	Oui	-	Tableau d'adresses email (max : 10 000)
`smtp_check`	boolean	Non	`true`	Effectuer une vérification SMTP
`webhook_url`	string	Non	-	URL pour recevoir la notification de fin

Réponse

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 3,
  "processed": 0,
  "valid": 0,
  "invalid": 0,
  "unknown": 0,
  "credits_used": 3,
  "created_at": "2025-01-15T10:30:00Z"
}

Obtenir le Statut d'une Tâche en Masse

Vérifiez le statut d'une tâche de vérification en masse.

GET /verify/bulk/{job_id}

Réponse (En Cours)

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 1000,
  "processed": 450,
  "valid": 380,
  "invalid": 50,
  "unknown": 20,
  "progress_percent": 45,
  "created_at": "2025-01-15T10:30:00Z"
}

Réponse (Terminée)

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "total": 1000,
  "processed": 1000,
  "valid": 850,
  "invalid": 100,
  "unknown": 50,
  "progress_percent": 100,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z"
}

Valeurs de Statut de Tâche

Statut	Description
`pending`	Tâche en file d'attente
`processing`	Tâche en cours de traitement
`completed`	Tâche terminée avec succès
`failed`	Tâche échouée (voir champ erreur)

Obtenir les Résultats d'une Tâche en Masse

Récupérez les résultats de vérification d'une tâche en masse terminée.

GET /verify/bulk/{job_id}/results

Paramètres de Requête

Paramètre	Type	Défaut	Description
`limit`	integer	100	Résultats par page (max : 1000)
`offset`	integer	0	Position de départ
`status`	string	-	Filtrer par statut : `valid`, `invalid`, `unknown`

Réponse

{
  "job_id": "job_abc123xyz",
  "total": 1000,
  "limit": 100,
  "offset": 0,
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "result": {
        "deliverable": true,
        "disposable": false,
        "role": false
      },
      "score": 0.95
    },
    {
      "email": "user2@example.com",
      "status": "invalid",
      "result": {
        "deliverable": false,
        "reason": "mailbox_not_found"
      },
      "score": 0.10
    }
  ]
}

Vérifier les Crédits

Obtenez le solde de crédits actuel et les informations d'utilisation.

GET /credits

Réponse

{
  "available": 9500,
  "used": 500,
  "total": 10000,
  "plan": "Professional",
  "resets_at": "2025-02-01T00:00:00Z",
  "rate_limit": {
    "requests_per_hour": 10000,
    "remaining": 9850
  }
}

Webhooks

Créer un Webhook

POST /webhooks

{
  "url": "https://your-app.com/webhooks/emailverify",
  "events": ["verification.completed", "bulk.completed"],
  "secret": "your-webhook-secret"
}

Lister les Webhooks

GET /webhooks

Supprimer un Webhook

DELETE /webhooks/{webhook_id}

Événements Webhook

Événement	Description
`verification.completed`	Vérification d'email unique terminée
`bulk.completed`	Tâche en masse terminée
`bulk.failed`	Tâche en masse échouée
`credits.low`	Crédits en dessous du seuil

Charge Utile Webhook

{
  "event": "bulk.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "total": 1000,
    "valid": 850,
    "invalid": 100,
    "unknown": 50
  },
  "signature": "sha256=..."
}

Statut de Vérification

Statut	Signification	Action Recommandée
`valid`	L'email existe et peut recevoir des messages	Envoi sécurisé
`invalid`	L'email n'existe pas ou ne peut pas recevoir	Retirer de la liste
`unknown`	Impossible de déterminer la validité	Réessayer plus tard ou utiliser avec prudence
`accept_all`	Le domaine accepte tous les emails (catch-all)	Surveiller les rebonds

Réponses d'Erreur

Toutes les erreurs suivent un format cohérent :

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

Codes de Statut HTTP

Code	Description
`200`	Succès
`400`	Requête Invalide - Paramètres invalides
`401`	Non Autorisé - Clé API invalide ou manquante
`403`	Interdit - Permissions insuffisantes
`404`	Non Trouvé - La ressource n'existe pas
`429`	Trop de Requêtes - Limite de taux dépassée
`500`	Erreur Serveur Interne
`503`	Service Non Disponible

Codes d'Erreur

Code	Statut HTTP	Description
`INVALID_API_KEY`	401	La clé API est invalide ou manquante
`RATE_LIMIT_EXCEEDED`	429	Trop de requêtes
`INSUFFICIENT_CREDITS`	403	Pas assez de crédits
`INVALID_EMAIL`	400	Le format de l'email est invalide
`INVALID_REQUEST`	400	Le corps de la requête est malformé
`JOB_NOT_FOUND`	404	ID de tâche en masse non trouvé
`TIMEOUT`	504	Délai de vérification expiré

Meilleures Pratiques

1. Utiliser des Variables d'Environnement

Ne codez jamais les clés API en dur :

// Bien
const apiKey = process.env.EMAILVERIFY_API_KEY;

// Mal - ne faites pas cela
const apiKey = 'bv_live_xxx';

2. Gérer les Limites de Taux

Implémentez un backoff exponentiel :

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. Utiliser le Mode en Masse pour Plusieurs Emails

Pour vérifier plus de 10 emails, utilisez le point de terminaison en masse :

// Bien - un seul appel API
const job = await client.verifyBulk(emails);

// Mal - beaucoup d'appels individuels
for (const email of emails) {
  await client.verify(email);
}

4. Implémenter des Webhooks pour les Tâches en Masse

N'interrogez pas constamment ; utilisez des webhooks :

// Soumettre avec webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

Guide de Démarrage Rapide

Types de Vérification

Guides d'Intégration

On this page