メール検証 API：開発者向け完全統合ガイド

単一メール検証

基本的なエンドポイントは、リクエストごとに 1 つのメールアドレスを検証します：

POST /v1/verify
{
  "email": "user@example.com"
}

レスポンス構造

{
  "email": "user@example.com",
  "is_valid": true,
  "is_deliverable": true,
  "is_disposable": false,
  "is_role_based": false,
  "is_catch_all": false,
  "is_free_provider": true,
  "syntax_valid": true,
  "domain_valid": true,
  "mx_found": true,
  "smtp_check": "passed",
  "risk_score": 15,
  "suggestion": null,
  "verification_time_ms": 1234
}

主要なレスポンスフィールド

バッチメール検証

大きなリストを検証するために、バッチエンドポイントは複数のメールを受け入れます：

POST /v1/verify/batch
{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}

バッチエンドポイントはメールを並列処理し、順次的な単一メールリクエストよりも速く結果を返します。ほとんどのサービスはバッチサイズを制限し（通常、リクエストあたり 100-1000 メール）、非常に大きなバッチは非同期で処理される場合があります。

バルクファイルアップロード

バッチエンドポイントには大きすぎるリストの場合、ファイルアップロード API は数百万のレコードを処理します：

const formData = new FormData();
formData.append('file', emailListFile);

const uploadResponse = await fetch('https://api.billionverify.com/v1/bulk/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const { job_id } = await uploadResponse.json();

ファイルアップロードエンドポイントは、進行状況を追跡するためのジョブ ID を返します。処理が完了すると結果が取得されます：

// ジョブステータスを確認
const statusResponse = await fetch(
  `https://api.billionverify.com/v1/bulk/status/${job_id}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const { status, progress, estimated_completion } = await statusResponse.json();

// 完了時に結果をダウンロード
if (status === 'completed') {
  const resultsResponse = await fetch(
    `https://api.billionverify.com/v1/bulk/download/${job_id}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
}

Webhook 通知

非同期処理の場合、検証が完了したときに通知を受け取るように Webhook を設定します：

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhooks/email-verification",
  "events": ["bulk.completed", "bulk.failed"],
  "secret": "your_webhook_secret"
}

Webhook はポーリングを排除し、バルク操作の効率を向上させます。

エラーハンドリング戦略

堅牢なエラーハンドリングにより、統合がユーザーエクスペリエンスを妨げることなく障害を適切に処理できます。

HTTP ステータスコード

メール検証 API は標準の HTTP ステータスコードを使用します：

リトライロジックの実装

ネットワークの問題と一時的なエラーには、リトライメカニズムが必要です：

async function verifyEmailWithRetry(email, maxRetries = 3) {
  const delays = [1000, 2000, 4000]; // 指数バックオフ

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.billionverify.com/v1/verify', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.BV_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ email })
      });

      if (response.status === 429) {
        // レート制限 - 待機してリトライ
        const retryAfter = response.headers.get('Retry-After') || delays[attempt];
        await sleep(parseInt(retryAfter) * 1000);
        continue;
      }

      if (response.status >= 500) {
        // サーバーエラー - バックオフしてリトライ
        await sleep(delays[attempt]);
        continue;
      }

      if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
      }

      return await response.json();

    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
      await sleep(delays[attempt]);
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

検証結果の処理

すべての検証が明確な答えを返すわけではありません。不確実な結果を適切に処理します：

function handleVerificationResult(result) {
  if (result.is_valid && result.is_deliverable) {
    return { status: 'valid', action: 'accept' };
  }

  if (!result.syntax_valid || !result.domain_valid) {
    return { status: 'invalid', action: 'reject' };
  }

  if (result.is_disposable) {
    return { status: 'risky', action: 'reject_or_warn' };
  }

  if (result.is_catch_all) {
    // 明確に検証できない - 監視付きで受け入れることを検討
    return { status: 'uncertain', action: 'accept_with_caution' };
  }

  if (result.risk_score > 70) {
    return { status: 'high_risk', action: 'manual_review' };
  }

  return { status: 'unknown', action: 'accept_with_monitoring' };
}

レート制限と最適化

メール検証 API は、公平な使用とシステムの安定性を確保するためにレート制限を実装しています。効果的な統合はこれらの制限を尊重しながら、スループットを最大化します。

レート制限の理解

レート制限は通常、複数のレベルで適用されます：

• 秒あたりのリクエスト数：1 秒あたりの最大 API 呼び出し数
• 分/時間あたりのリクエスト数：持続的なレート制限
• 日次/月次クォータ：合計検証許容量
• 同時接続数：同時リクエスト制限

レート制限情報のレスポンスヘッダーを確認してください：

const response = await fetch('https://api.billionverify.com/v1/verify', {
  // ... リクエストオプション
});

const rateLimit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const resetTime = response.headers.get('X-RateLimit-Reset');

console.log(`Rate limit: ${remaining}/${rateLimit}, resets at ${resetTime}`);

レート制限の実装

制限に達するのを避けるために、リクエストレートを積極的に管理します：

class RateLimiter {
  constructor(requestsPerSecond) {
    this.interval = 1000 / requestsPerSecond;
    this.lastRequest = 0;
  }

  async waitForSlot() {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;

    if (timeSinceLastRequest < this.interval) {
      await sleep(this.interval - timeSinceLastRequest);
    }

    this.lastRequest = Date.now();
  }
}

// 使用方法
const limiter = new RateLimiter(10); // 秒あたり 10 リクエスト

async function verifyEmailsWithRateLimit(emails) {
  const results = [];

  for (const email of emails) {
    await limiter.waitForSlot();
    const result = await verifyEmail(email);
    results.push(result);
  }

  return results;
}

バッチ処理の最適化

複数のメールを検証する際の効率を最大化します：

バッチエンドポイントを使用 各メールに対する単一のリクエストは、ネットワークラウンドトリップを無駄にします。バッチエンドポイントは、リクエストごとに複数のメールを検証します：

// 非効率：100 の個別リクエスト
for (const email of emails) {
  await verifyEmail(email);
}

// 効率的：1 つのバッチリクエスト
const results = await verifyEmailBatch(emails);

大きなリストをチャンク化 非常に大きなリストを最適なバッチサイズに分割します：

function chunkArray(array, chunkSize) {
  const chunks = [];
  for (let i = 0; i < array.length; i += chunkSize) {
    chunks.push(array.slice(i, i + chunkSize));
  }
  return chunks;
}

async function verifyLargeList(emails) {
  const chunks = chunkArray(emails, 100); // バッチあたり 100 メール
  const results = [];

  for (const chunk of chunks) {
    const batchResults = await verifyEmailBatch(chunk);
    results.push(...batchResults);
  }

  return results;
}

制限付き並列処理 レート制限を尊重しながら、複数のバッチを同時に処理します：

async function verifyWithConcurrency(emails, concurrency = 5) {
  const chunks = chunkArray(emails, 100);
  const results = [];

  for (let i = 0; i < chunks.length; i += concurrency) {
    const batch = chunks.slice(i, i + concurrency);
    const batchResults = await Promise.all(
      batch.map(chunk => verifyEmailBatch(chunk))
    );
    results.push(...batchResults.flat());
  }

  return results;
}

キャッシング戦略

検証結果をキャッシュすることで、API コストを削減し、繰り返しメールの応答時間を改善します。

いつキャッシュするか

次の場合に検証結果をキャッシュします：

• 同じメールが複数回検証される可能性がある
• リアルタイム検証が重要ではない
• コストの最適化が重要

次の場合はキャッシュしないでください：

• 鮮度が重要（例：高額取引）
• ユースケースでメールのステータスが頻繁に変わる
• ストレージコストが API コストを超える

キャッシュの実装

class VerificationCache {
  constructor(ttlMs = 24 * 60 * 60 * 1000) { // デフォルト 24 時間 TTL
    this.cache = new Map();
    this.ttl = ttlMs;
  }

  get(email) {
    const entry = this.cache.get(email.toLowerCase());

    if (!entry) return null;

    if (Date.now() > entry.expiry) {
      this.cache.delete(email.toLowerCase());
      return null;
    }

    return entry.result;
  }

  set(email, result) {
    this.cache.set(email.toLowerCase(), {
      result,
      expiry: Date.now() + this.ttl
    });
  }
}

// 使用方法
const cache = new VerificationCache();

async function verifyEmailCached(email) {
  const cached = cache.get(email);
  if (cached) {
    return { ...cached, fromCache: true };
  }

  const result = await verifyEmail(email);
  cache.set(email, result);

  return { ...result, fromCache: false };
}

キャッシュ TTL の考慮事項

結果タイプが異なれば、キャッシュ期間も異なります：

セキュリティのベストプラクティス

外部 API の統合は、認証以外のセキュリティの考慮事項を導入します。

入力検証

API に送信する前にメールを検証します：

function isValidEmailFormat(email) {
  if (typeof email !== 'string') return false;
  if (email.length > 254) return false;

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

async function verifyEmailSafely(email) {
  if (!isValidEmailFormat(email)) {
    return { is_valid: false, reason: 'Invalid format' };
  }

  return await verifyEmail(email);
}

セキュアなログ記録

完全な API キーや機密データをログに記録しないでください：

function logApiRequest(email, response) {
  // ログに記録しない：API キー、本番環境での完全なメールアドレス
  console.log({
    email_domain: email.split('@')[1],
    status: response.status,
    is_valid: response.is_valid,
    timestamp: new Date().toISOString()
  });
}

HTTPS のみ

API 通信には常に HTTPS を使用してください。本番環境では SSL 証明書を検証します：

// Node.js - 本番環境で証明書検証を無効にしないでください
const https = require('https');

const agent = new https.Agent({
  rejectUnauthorized: true // デフォルトですが、明示的に
});

人気のフレームワークとの統合

Express.js ミドルウェア

メール確認用の再利用可能なミドルウェアを作成します：

const emailVerificationMiddleware = async (req, res, next) => {
  const { email } = req.body;

  if (!email) {
    return next();
  }

  try {
    const result = await verifyEmail(email);
    req.emailVerification = result;

    if (!result.is_valid) {
      return res.status(400).json({
        error: 'Invalid email address',
        details: result
      });
    }

    next();
  } catch (error) {
    // フェイルオープン - API エラーで登録をブロックしない
    req.emailVerification = { verified: false, error: error.message };
    next();
  }
};

// 使用方法
app.post('/register', emailVerificationMiddleware, (req, res) => {
  // req.emailVerification には検証結果が含まれています
});

React Hook

フロントエンドメール検証用のカスタムフックを作成します：

import { useState, useCallback } from 'react';
import debounce from 'lodash/debounce';

function useEmailVerification() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const verify = useCallback(
    debounce(async (email) => {
      if (!email || !email.includes('@')) {
        setResult(null);
        return;
      }

      setLoading(true);
      setError(null);

      try {
        const response = await fetch('/api/verify-email', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ email })
        });

        const data = await response.json();
        setResult(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }, 500),
    []
  );

  return { verify, result, loading, error };
}

監視と分析

API 使用状況と検証結果を追跡して、統合を最適化します。

監視すべき主要メトリクス

• API レスポンス時間：レイテンシのトレンドを追跡
• エラー率：タイプ別に障害を監視
• キャッシュヒット率：キャッシングの効果を測定
• 検証分布：有効/無効/リスクのパーセンテージを追跡
• 検証あたりのコスト：実際のコストを計算

分析用のログ記録

function logVerification(email, result, metadata) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    email_domain: email.split('@')[1],
    is_valid: result.is_valid,
    is_deliverable: result.is_deliverable,
    is_disposable: result.is_disposable,
    risk_score: result.risk_score,
    response_time_ms: metadata.responseTime,
    from_cache: metadata.fromCache,
    source: metadata.source // 登録、インポートなど
  };

  // 分析システムに送信
  analytics.track('email_verification', logEntry);
}

BillionVerify API 統合

BillionVerify は、開発者向けに設計された包括的なメール検証 API を提供します。当社の配信性ガイドでは API の最適な使用方法についても詳しく解説しています。API は複数の検証技術を 1 回の呼び出しで組み合わせ、詳細な洞察とともに高速で正確な結果を提供します。

クイックスタート

async function verifyWithBillionVerify(email) {
  const response = await fetch('https://api.billionverify.com/v1/verify', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BV_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  return await response.json();
}

機能

• リアルタイム検証：単一メール検証で 1 秒未満のレスポンス時間
• バッチ処理：リクエストあたり最大 1000 件のメールを検証
• バルクファイルアップロード：非同期ジョブ処理で数百万のレコードを処理
• 包括的なチェック：構文、ドメイン、MX、SMTP、使い捨て、キャッチオール検出
• リスクスコアリング：バイナリの有効/無効を超えた微妙なリスク評価
• タイポ提案：一般的なタイポを検出し、修正を提案
• Webhook サポート：バルクジョブ完了の通知を受信

API ドキュメントは、すべてのエンドポイント、レスポンス形式、および複数のプログラミング言語での統合例に関する詳細情報を提供します。

まとめ

メール検証 API の統合は、アプリケーションがメールデータ品質を処理する方法を変革します。登録時のリアルタイム検証から既存リストのバッチ処理まで、API は検証システムの構築と維持の複雑さなしに、包括的なメール確認のためのインフラストラクチャを提供します。

統合を成功させるための重要なポイント：

1. ユースケースに適したエンドポイントを選択：リアルタイムには単一検証、中規模リストにはバッチ、大規模データセットにはバルクアップロード
2. 堅牢なエラーハンドリングを実装：リトライロジックとグレースフルデグラデーション
3. レート制限を尊重：クライアント側のスロットリングと効率的なバッチ処理
4. 戦略的にキャッシュ：コストを削減しパフォーマンスを向上
5. 監視と分析：検証結果を継続的に改善

新しいアプリケーションを構築する場合でも、既存のシステムを改善する場合でも、BillionVerify のようなメール検証 API は、データベース内のすべてのメールアドレスが有効で、配信可能で、安全に使用できることを保証するために必要なツールを提供します。

今日から統合を開始して、プロフェッショナルなメールバリデーターがアプリケーションのデータ品質とメール配信性にもたらす違いを体験してください。