EmailVerify LogoEmailVerify
SDKs

TypeScript SDK

TypeScript email checker SDK with full type definitions. Type-safe email verification for Node.js.

Le SDK EmailVerify TypeScript fournit des définitions de type complètes pour une vérification d'emails type-safe dans les projets TypeScript.

Le SDK TypeScript partage le même package que le SDK Node.js mais avec un support TypeScript complet.

Installation

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

Démarrage Rapide

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

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

const result: VerificationResult = await client.verify('user@example.com');
console.log(result.status); // Type: 'valid' | 'invalid' | 'unknown' | 'accept_all'

Définitions de Type

Options du Client

interface ClientOptions {
  apiKey: string;
  timeout?: number;           // Par défaut : 30000ms
  retries?: number;           // Par défaut : 3
  retryDelay?: number;        // Par défaut : 1000ms
  retryMaxDelay?: number;     // Par défaut : 30000ms
  baseUrl?: string;           // Par défaut : 'https://api.emailverify.ai'
}

Résultat de Vérification

interface VerificationResult {
  email: string;
  status: VerificationStatus;
  result: ResultDetails;
  score: number;
  reason: string | null;
}

type VerificationStatus = 'valid' | 'invalid' | 'unknown' | 'accept_all';

interface ResultDetails {
  deliverable: boolean | null;
  valid_format: boolean;
  valid_domain: boolean;
  valid_mx: boolean;
  disposable: boolean;
  role: boolean;
  catchall: boolean;
  free: boolean;
  smtp_valid: boolean | null;
}

Types de Tâche en Masse

interface BulkJob {
  id: string;
  status: BulkJobStatus;
  total: number;
  processed: number;
  valid: number;
  invalid: number;
  unknown: number;
  created_at: string;
  completed_at: string | null;
}

type BulkJobStatus = 'pending' | 'processing' | 'completed' | 'failed';

interface BulkJobResults {
  job_id: string;
  results: VerificationResult[];
}

Types d'Erreurs

class EmailVerifyError extends Error {
  code: string;
  statusCode?: number;
}

class AuthenticationError extends EmailVerifyError {
  code: 'authentication_error';
}

class RateLimitError extends EmailVerifyError {
  code: 'rate_limit_error';
  retryAfter: number;
}

class ValidationError extends EmailVerifyError {
  code: 'validation_error';
  field?: string;
}

Configuration

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
  timeout: 30000,
  retries: 3,
});

Vérification Unique

Basic Usage

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

// TypeScript knows all properties and their types
if (result.status === 'valid') {
  console.log(`Score: ${result.score}`);
  console.log(`Deliverable: ${result.result.deliverable}`);
}

Avec Options

interface VerifyOptions {
  smtpCheck?: boolean;
  timeout?: number;
}

const result = await client.verify('user@example.com', {
  smtpCheck: true,
  timeout: 5000,
});

Type Guards

function isValidEmail(result: VerificationResult): boolean {
  return result.status === 'valid' && result.score >= 0.8;
}

function isSafeForMarketing(result: VerificationResult): boolean {
  return (
    result.status === 'valid' &&
    !result.result.disposable &&
    !result.result.role
  );
}

Vérification en Masse

Soumettre une Tâche

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

const job: BulkJob = await client.verifyBulk(emails);

Obtenir le Statut

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

// Type-safe status checking
switch (status.status) {
  case 'pending':
    console.log('Job is queued');
    break;
  case 'processing':
    console.log(`Progress: ${status.processed}/${status.total}`);
    break;
  case 'completed':
    console.log(`Done! Valid: ${status.valid}, Invalid: ${status.invalid}`);
    break;
  case 'failed':
    console.log('Job failed');
    break;
}

Obtenir les Résultats

const results: BulkJobResults = await client.getBulkJobResults(job.id);

results.results.forEach((result) => {
  console.log(`${result.email}: ${result.status}`);
});

Gestion des Erreurs

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

async function verifyEmail(email: string): Promise<VerificationResult | null> {
  try {
    return await client.verify(email);
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error('Invalid API key');
    } else if (error instanceof RateLimitError) {
      console.error(`Rate limited. Retry after ${error.retryAfter}s`);
    } else if (error instanceof ValidationError) {
      console.error(`Invalid input: ${error.message}`);
    } else if (error instanceof EmailVerifyError) {
      console.error(`API error: ${error.message}`);
    }
    return null;
  }
}

Utilitaires Génériques

Fonction de Validation Type-Safe

type ValidationResult =
  | { valid: true; score: number }
  | { valid: false; reason: string; message: string };

async function validateEmail(email: string): Promise<ValidationResult> {
  const result = await client.verify(email);

  if (result.status === 'invalid') {
    return {
      valid: false,
      reason: 'invalid_email',
      message: 'This email address is invalid',
    };
  }

  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: 'Disposable emails are not allowed',
    };
  }

  return {
    valid: true,
    score: result.score,
  };
}

Traitement de Résultat Personnalisé

interface ProcessedResult {
  email: string;
  isValid: boolean;
  riskLevel: 'low' | 'medium' | 'high';
  flags: string[];
}

function processResult(result: VerificationResult): ProcessedResult {
  const flags: string[] = [];

  if (result.result.disposable) flags.push('disposable');
  if (result.result.role) flags.push('role');
  if (result.result.catchall) flags.push('catchall');
  if (result.result.free) flags.push('free');

  let riskLevel: 'low' | 'medium' | 'high';
  if (result.score >= 0.8) {
    riskLevel = 'low';
  } else if (result.score >= 0.5) {
    riskLevel = 'medium';
  } else {
    riskLevel = 'high';
  }

  return {
    email: result.email,
    isValid: result.status === 'valid',
    riskLevel,
    flags,
  };
}

Intégration avec les Frameworks

Routeur App Next.js

// app/api/verify/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify, VerificationResult } from '@emailverify/node';

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

interface RequestBody {
  email: string;
}

interface ResponseBody {
  valid: boolean;
  score?: number;
  message?: string;
}

export async function POST(request: NextRequest): Promise<NextResponse<ResponseBody>> {
  const body: RequestBody = await request.json();

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

    if (result.status === 'invalid') {
      return NextResponse.json(
        { valid: false, message: 'Invalid email address' },
        { status: 400 }
      );
    }

    return NextResponse.json({
      valid: true,
      score: result.score,
    });
  } catch (error) {
    return NextResponse.json(
      { valid: false, message: 'Verification failed' },
      { status: 500 }
    );
  }
}

Service NestJS

// email-verification.service.ts
import { Injectable } from '@nestjs/common';
import { EmailVerify, VerificationResult } from '@emailverify/node';

@Injectable()
export class EmailVerificationService {
  private client: EmailVerify;

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

  async verify(email: string): Promise<VerificationResult> {
    return this.client.verify(email);
  }

  async isValidForRegistration(email: string): Promise<boolean> {
    const result = await this.verify(email);
    return (
      result.status === 'valid' &&
      !result.result.disposable &&
      result.score >= 0.7
    );
  }
}

Express avec TypeScript

import express, { Request, Response } from 'express';
import { EmailVerify, VerificationResult } from '@emailverify/node';

const app = express();
app.use(express.json());

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

interface VerifyRequest {
  email: string;
}

interface VerifyResponse {
  success: boolean;
  data?: VerificationResult;
  error?: string;
}

app.post('/verify', async (
  req: Request<{}, VerifyResponse, VerifyRequest>,
  res: Response<VerifyResponse>
) => {
  try {
    const result = await client.verify(req.body.email);
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  }
});

Intégration de Schéma Zod

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

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

const emailSchema = z.string().email().refine(
  async (email) => {
    try {
      const result = await client.verify(email);
      return result.status === 'valid';
    } catch {
      return false;
    }
  },
  { message: 'Email address is not valid or deliverable' }
);

// Usage
async function validateEmail(email: string) {
  return emailSchema.parseAsync(email);
}

Meilleures Pratiques

1. Utiliser des Vérifications Null Strictes

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}

// Code with proper null handling
const result = await client.verify(email);
if (result.result.deliverable !== null) {
  console.log(`Deliverable: ${result.result.deliverable}`);
}

2. Créer des Wrappers Type-Safe

// verification.ts
export async function verifyAndCategorize(email: string) {
  const result = await client.verify(email);

  return {
    email: result.email,
    category: categorize(result),
    score: result.score,
    details: result.result,
  } as const;
}

function categorize(result: VerificationResult) {
  if (result.status !== 'valid') return 'invalid';
  if (result.result.disposable) return 'disposable';
  if (result.result.role) return 'role';
  return 'valid';
}

Prochaines Étapes

SDK Node.js

Documentation complète du SDK Node.js

Référence API

Documentation détaillée de l'API

Guides d'Intégration

Intégrations de plateformes

Python SDK

Python email checker SDK. pip install, verify emails with Python. Code examples and async support.

Go SDK

Go email checker SDK. Install, configure, verify emails with Golang. Code examples included.

On this page

InstallationDémarrage RapideDéfinitions de TypeOptions du ClientRésultat de VérificationTypes de Tâche en MasseTypes d'ErreursConfigurationVérification UniqueBasic UsageAvec OptionsType GuardsVérification en MasseSoumettre une TâcheObtenir le StatutObtenir les RésultatsGestion des ErreursUtilitaires GénériquesFonction de Validation Type-SafeTraitement de Résultat PersonnaliséIntégration avec les FrameworksRouteur App Next.jsService NestJSExpress avec TypeScriptIntégration de Schéma ZodMeilleures Pratiques1. Utiliser des Vérifications Null Strictes2. Créer des Wrappers Type-SafeProchaines Étapes