Node.js SDK

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

官方 EmailVerify Node.js SDK 提供了一種簡單高效的方式，將郵箱驗證整合到您的 Node.js 應用程式中。

安裝

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

快速入門

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

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

// 驗證單個郵箱
const result = await client.verify('user@example.com');
console.log(result.status); // 'valid'、'invalid'、'unknown' 或 'accept_all'

配置

客戶端選項

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

  // 可選配置
  timeout: 30000,           // 請求逾時（毫秒）（預設：30000）
  retries: 3,               // 重試次數（預設：3）
  baseUrl: 'https://api.emailverify.ai', // 自訂 API URL
});

環境變數

我們建議將您的 API Key 儲存在環境變數中：

# .env
EMAILVERIFY_API_KEY=your_api_key_here

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

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

單一郵箱驗證

基本驗證

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

帶選項的驗證

const result = await client.verify('user@example.com', {
  smtpCheck: true,      // 啟用 SMTP 驗證
  timeout: 5000,        // 此請求的自訂逾時
});

回應結構

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

批量驗證

提交批量任務

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

const job = await client.verifyBulk(emails);
console.log(`任務 ID: ${job.id}`);
console.log(`狀態: ${job.status}`);

檢查任務狀態

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

獲取結果

// 等待任務完成
const results = await client.getBulkJobResults(job.id);

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

Webhook 通知

您可以配置 webhook 來接收任務完成時的通知，而不是輪詢：

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

額度管理

檢查可用額度

const credits = await client.getCredits();

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

錯誤處理

錯誤類型

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('無效的 API Key');
  } else if (error instanceof RateLimitError) {
    console.error(`速率限制。請在 ${error.retryAfter} 秒後重試`);
  } else if (error instanceof ValidationError) {
    console.error(`無效的輸入: ${error.message}`);
  } else if (error instanceof EmailVerifyError) {
    console.error(`API 錯誤: ${error.message}`);
  }
}

重試邏輯

SDK 會自動重試失敗的請求，並使用指數退避：

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
  retries: 5,                    // 最大重試次數
  retryDelay: 1000,              // 初始延遲（毫秒）
  retryMaxDelay: 30000,          // 重試之間的最大延遲
});

框架整合

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: '請輸入有效的郵箱地址',
      });
    }

    if (result.result.disposable) {
      return res.status(400).json({
        valid: false,
        message: '不允許使用一次性郵箱',
      });
    }

    res.json({ valid: true, result });
  } catch (error) {
    res.status(500).json({ error: '驗證失敗' });
  }
});

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

Next.js API Route

// 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: '不允許的方法' });
  }

  const { email } = req.body;

  try {
    const result = await client.verify(email);
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: '驗證失敗' });
  }
}

完整範例

使用郵箱驗證的使用者註冊

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

  // 拒絕無效郵箱
  if (result.status === 'invalid') {
    return {
      valid: false,
      reason: 'invalid_email',
      message: '此郵箱地址無效',
    };
  }

  // 拒絕一次性郵箱
  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: '請使用永久郵箱地址',
    };
  }

  // 警告角色郵箱
  if (result.result.role) {
    return {
      valid: true,
      warning: 'role_based',
      message: '建議使用個人郵箱',
    };
  }

  // 接受有效郵箱
  return {
    valid: true,
    score: result.score,
  };
}

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

TypeScript 支援

SDK 內建 TypeScript 定義：

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