EmailVerify LogoEmailVerify
SDK

TypeScript SDK

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

EmailVerify TypeScript SDK 为 TypeScript 项目提供完整的类型定义,实现类型安全的邮箱验证。

TypeScript SDK 与 Node.js SDK 使用相同的包，但提供完整的 TypeScript 支持。

安装

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

快速开始

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

类型定义

客户端选项

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

验证结果

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

批量任务 类型

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

错误类型

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

配置

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

单个验证

基本使用示例

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

// TypeScript 了解所有属性及其类型
if (result.status === 'valid') {
  console.log(`分数: ${result.score}`);
  console.log(`可递送: ${result.result.deliverable}`);
}

使用选项

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

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

类型守卫

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

批量验证

提交任务

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

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

获取状态

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

// 类型安全的状态检查
switch (status.status) {
  case 'pending':
    console.log('任务已排队');
    break;
  case 'processing':
    console.log(`进度: ${status.processed}/${status.total}`);
    break;
  case 'completed':
    console.log(`完成! 有效: ${status.valid}, 无效: ${status.invalid}`);
    break;
  case 'failed':
    console.log('任务失败');
    break;
}

获取结果

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

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

错误处理

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('API 密钥无效');
    } else if (error instanceof RateLimitError) {
      console.error(`访问频率受限。请在 ${error.retryAfter}s 后重试`);
    } else if (error instanceof ValidationError) {
      console.error(`输入无效: ${error.message}`);
    } else if (error instanceof EmailVerifyError) {
      console.error(`API 错误: ${error.message}`);
    }
    return null;
  }
}

通用工具

类型安全的验证函数

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: '此邮箱地址无效',
    };
  }

  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: '不允许使用一次性邮箱',
    };
  }

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

自定义结果处理

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

框架集成

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: '无效的邮箱地址' },
        { status: 400 }
      );
    }

    return NextResponse.json({
      valid: true,
      score: result.score,
    });
  } catch (error) {
    return NextResponse.json(
      { valid: false, message: '验证失败' },
      { 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 with 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 : '未知错误',
    });
  }
});

Zod Schema 集成

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: '邮箱地址无效或无法递送' }
);

// 使用方法
async function validateEmail(email: string) {
  return emailSchema.parseAsync(email);
}

最佳实践

1. 使用严格空值检查

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

// 具有适当空值处理的代码
const result = await client.verify(email);
if (result.result.deliverable !== null) {
  console.log(`可递送: ${result.result.deliverable}`);
}

2. 创建类型安全的包装器

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

下一步

Node.js SDK

完整的 Node.js SDK 文档

API 参考

详细的 API 文档

集成指南

平台集成指南

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

安装快速开始类型定义客户端选项验证结果批量任务 类型错误类型配置单个验证基本使用示例使用选项类型守卫批量验证提交任务获取状态获取结果错误处理通用工具类型安全的验证函数自定义结果处理框架集成Next.js App RouterNestJS ServiceExpress with TypeScriptZod Schema 集成最佳实践1. 使用严格空值检查2. 创建类型安全的包装器下一步