TypeScript SDK

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

Das EmailVerify TypeScript SDK bietet vollständige Typdefinitionen für typsichere E-Mail-Verifizierung in TypeScript-Projekten.

Das TypeScript SDK teilt sich dasselbe Paket wie das Node.js SDK, jedoch mit vollständiger TypeScript-Unterstützung.

Installation

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

Schnellstart

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); // Typ: 'valid' | 'invalid' | 'unknown' | 'accept_all'

Typdefinitionen

Client-Optionen

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

Verifizierungsergebnis

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;
}

Massenauftrags-Typen

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[];
}

Fehlertypen

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;
}

Konfiguration

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

Einzelverifizierung

Grundlegende Verwendung

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

// TypeScript kennt alle Eigenschaften und ihre Typen
if (result.status === 'valid') {
  console.log(`Score: ${result.score}`);
  console.log(`Deliverable: ${result.result.deliverable}`);
}

Mit Optionen

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
  );
}

Massenverifizierung

Auftrag einreichen

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

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

Status abrufen

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

// Typsichere Statusprüfung
switch (status.status) {
  case 'pending':
    console.log('Auftrag ist in der Warteschlange');
    break;
  case 'processing':
    console.log(`Fortschritt: ${status.processed}/${status.total}`);
    break;
  case 'completed':
    console.log(`Fertig! Gültig: ${status.valid}, Ungültig: ${status.invalid}`);
    break;
  case 'failed':
    console.log('Auftrag fehlgeschlagen');
    break;
}

Ergebnisse abrufen

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

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

Fehlerbehandlung

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('Ungültiger API-Schlüssel');
    } else if (error instanceof RateLimitError) {
      console.error(`Rate-Limit erreicht. Wiederholen nach ${error.retryAfter}s`);
    } else if (error instanceof ValidationError) {
      console.error(`Ungültige Eingabe: ${error.message}`);
    } else if (error instanceof EmailVerifyError) {
      console.error(`API-Fehler: ${error.message}`);
    }
    return null;
  }
}

Generische Hilfsfunktionen

Typsichere Validierungsfunktion

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: 'Diese E-Mail-Adresse ist ungültig',
    };
  }

  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: 'Wegwerf-E-Mails sind nicht erlaubt',
    };
  }

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

Benutzerdefinierte Ergebnisverarbeitung

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,
  };
}

Framework-Integration

Next.js App Router

// 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: 'Ungültige E-Mail-Adresse' },
        { status: 400 }
      );
    }

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

NestJS Service

// 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 mit 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 : 'Unbekannter Fehler',
    });
  }
});

Zod Schema Integration

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: 'E-Mail-Adresse ist nicht gültig oder zustellbar' }
);

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

Best Practices

1. Strenge Null-Prüfungen verwenden

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

// Code mit korrekter Null-Behandlung
const result = await client.verify(email);
if (result.result.deliverable !== null) {
  console.log(`Zustellbar: ${result.result.deliverable}`);
}

2. Typsichere Wrapper erstellen

// 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';
}

Nächste Schritte

Node.js SDK

Vollständige Node.js SDK Dokumentation

API-Referenz

Detaillierte API-Dokumentation

Integrationsleitfäden

Plattformintegrationen

TypeScript SDK

Node.js SDK

API-Referenz

Integrationsleitfäden

On this page