Node.js SDK

Node.js email checker SDK. Install, configure, verify emails with JavaScript. Code examples included.

Le SDK officiel EmailVerify pour Node.js fournit un moyen simple et efficace d'intégrer la vérification d'emails dans vos applications Node.js.

Installation

npm install @emailverify/node
# ou
yarn add @emailverify/node
# ou
pnpm add @emailverify/node

Démarrage Rapide

import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

// Vérifier un seul email
const result = await client.verify('user@example.com');
console.log(result.status); // 'valid', 'invalid', 'unknown', ou 'accept_all'

Configuration

Options du Client

const client = new EmailVerify({
  apiKey: 'your-api-key',

  // Configurations optionnelles
  timeout: 30000,           // Délai de requête en ms (par défaut : 30000)
  retries: 3,               // Nombre de tentatives (par défaut : 3)
  baseUrl: 'https://api.emailverify.ai', // URL API personnalisée
});

Variables d'Environnement

Nous recommandons de stocker votre clé API dans des variables d'environnement :

# .env
EMAILVERIFY_API_KEY=your_api_key_here

import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

Vérification d'Email Unique

Vérification Basique

const result = await client.verify('user@example.com');

console.log({
  email: result.email,
  status: result.status,
  score: result.score,
  deliverable: result.result.deliverable,
  disposable: result.result.disposable,
  role: result.result.role,
});

Vérification avec Options

const result = await client.verify('user@example.com', {
  smtpCheck: true,      // Activer la vérification SMTP
  timeout: 5000,        // Délai personnalisé pour cette requête
});

Structure de Réponse

interface VerificationResult {
  email: string;
  status: 'valid' | 'invalid' | 'unknown' | 'accept_all';
  result: {
    deliverable: boolean | null;
    valid_format: boolean;
    valid_domain: boolean;
    valid_mx: boolean;
    disposable: boolean;
    role: boolean;
    catchall: boolean;
    free: boolean;
    smtp_valid: boolean | null;
  };
  score: number;
  reason: string | null;
}

Vérification en Masse

Soumettre une Tâche en Masse

const emails = [
  'user1@example.com',
  'user2@example.com',
  'user3@example.com',
];

const job = await client.verifyBulk(emails);
console.log(`ID de tâche : ${job.id}`);
console.log(`Statut : ${job.status}`);

Vérifier le Statut de la Tâche

const status = await client.getBulkJobStatus(job.id);

console.log({
  id: status.id,
  status: status.status,      // 'pending', 'processing', 'completed', 'failed'
  total: status.total,
  processed: status.processed,
  valid: status.valid,
  invalid: status.invalid,
});

Obtenir les Résultats

// Attendre la fin de la tâche
const results = await client.getBulkJobResults(job.id);

for (const result of results) {
  console.log(`${result.email}: ${result.status}`);
}

Notifications par Webhook

Au lieu de l'interrogation, configurez un webhook pour recevoir des notifications lorsque la tâche est terminée :

const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-domain.com/webhooks/emailverify',
});

Gestion des Crédits

Vérifier les Crédits Disponibles

const credits = await client.getCredits();

console.log({
  available: credits.available,
  used: credits.used,
  total: credits.total,
});

Gestion des Erreurs

Types d'Erreurs

import {
  EmailVerify,
  EmailVerifyError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from '@emailverify/node';

try {
  const result = await client.verify('invalid-email');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Clé API invalide');
  } else if (error instanceof RateLimitError) {
    console.error(`Limite de débit atteinte. Réessayer après ${error.retryAfter} secondes`);
  } else if (error instanceof ValidationError) {
    console.error(`Entrée invalide : ${error.message}`);
  } else if (error instanceof EmailVerifyError) {
    console.error(`Erreur API : ${error.message}`);
  }
}

Logique de Nouvelle Tentative

Le SDK réessaie automatiquement les requêtes échouées avec un délai exponentiel :

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
  retries: 5,                    // Tentatives max
  retryDelay: 1000,              // Délai initial en ms
  retryMaxDelay: 30000,          // Délai max entre tentatives
});

Intégration avec les Frameworks

Express.js

import express from 'express';
import { EmailVerify } from '@emailverify/node';

const app = express();
const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

app.post('/api/verify-email', async (req, res) => {
  const { email } = req.body;

  try {
    const result = await client.verify(email);

    if (result.status === 'invalid') {
      return res.status(400).json({
        valid: false,
        message: 'Veuillez entrer une adresse email valide',
      });
    }

    if (result.result.disposable) {
      return res.status(400).json({
        valid: false,
        message: 'Les emails jetables ne sont pas autorisés',
      });
    }

    res.json({ valid: true, result });
  } catch (error) {
    res.status(500).json({ error: 'Échec de la vérification' });
  }
});

Fastify

import Fastify from 'fastify';
import { EmailVerify } from '@emailverify/node';

const fastify = Fastify();
const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

fastify.post('/verify', async (request, reply) => {
  const { email } = request.body;
  const result = await client.verify(email);
  return result;
});

Route API Next.js

// pages/api/verify.js
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Méthode non autorisée' });
  }

  const { email } = req.body;

  try {
    const result = await client.verify(email);
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: 'Échec de la vérification' });
  }
}

Exemple Complet

Inscription Utilisateur avec Vérification d'Email

import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

async function validateRegistrationEmail(email) {
  const result = await client.verify(email);

  // Rejeter les emails invalides
  if (result.status === 'invalid') {
    return {
      valid: false,
      reason: 'invalid_email',
      message: 'Cette adresse email est invalide',
    };
  }

  // Rejeter les emails jetables
  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: 'Veuillez utiliser une adresse email permanente',
    };
  }

  // Avertir sur les emails basés sur des rôles
  if (result.result.role) {
    return {
      valid: true,
      warning: 'role_based',
      message: 'Il est recommandé d\'utiliser un email personnel',
    };
  }

  // Accepter les emails valides
  return {
    valid: true,
    score: result.score,
  };
}

// Utilisation
const validation = await validateRegistrationEmail('user@example.com');
if (!validation.valid) {
  console.error(validation.message);
}

Support TypeScript

Le SDK inclut des définitions TypeScript prêtes à l'emploi :

import {
  EmailVerify,
  VerificationResult,
  BulkJob,
  ClientOptions
} from '@emailverify/node';

const options: ClientOptions = {
  apiKey: process.env.EMAILVERIFY_API_KEY!,
  timeout: 30000,
};

const client = new EmailVerify(options);

const result: VerificationResult = await client.verify('user@example.com');