検証理由コード

すべての検証結果には reason フィールドが含まれており、そのメールアドレスがそのステータスを受けた理由を説明します。このリファレンスを使用して、正確なフィルタリングロジックを構築し、予期しない結果を診断し、送信戦略を最適化してください。

reason の仕組み

reason フィールドは、すべての検証レスポンスで status フィールドと並んで表示されます：

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "smtp_deliverable"
}

reason は安定した文字列識別子です——フィルタリングルールや下流の条件付きロジックで直接使用できます。

Valid（有効）

status: "valid" のメールは配信可能と確認されています。

Invalid（無効）

status: "invalid" のメールはリストから削除してください——配信は不可能です。

Unknown（不明）

status: "unknown" のメールは決定的に検証できませんでした。一部は一時的なもの（再試行可能）で、その他は構造的な制限を表します。

Risky（リスクあり）

status: "risky" のメールは中程度の配信リスクがあります。

Catch-all（全受信）

status: "catchall" のメールは、すべてのアドレスのメールを受け入れるドメインに属しています。個別の配信可能性は確認できません。

Role（役割アドレス）

status: "role" のメールは共有受信箱に属しています（例：info@、support@、noreply@）。これらのアドレスは通常配信可能ですが、エンゲージメント率が低い。

役割アドレスは基礎となる SMTP チェックの reason を継承します——このステータスには専用の reason コードは存在しません。例えば、SMTP を通過した役割アドレスは reason: "smtp_deliverable" を表示します。

Disposable（使い捨て）

status: "disposable" のメールは一時的なメールサービスに属しています。これらを受け入れると、通常は低品質な登録につながります。

フィルタリングでの reason の使用

status と reason を組み合わせて正確なリストセグメンテーションを実現できます。例えば、一時的な問題のみが原因で unknown の unknown メールを保持するには：

function isRetryableUnknown(result) {
  const retryableReasons = new Set([
    'smtp_eof_blocked', 'smtp_timeout', 'smtp_rate_limited',
    'smtp_greylisted', 'mimecast_greylist', 'proofpoint_ad_lookup',
    'policy_temp_fail', 'google_rate_limit', 'm365_ip_rep_block',
    'dns_timeout', 'dns_lookup_error', 'yahoo_api_error',
    'yahoo_api_unavailable', 'yahoo_api_eof',
    'yahoo_api_unavailable_after_fallback', 'internal_verifier_error',
    'rate_limited', 'mx_only_verification_semaphore_timeout',
  ]);
  return result.status === 'unknown' && retryableReasons.has(result.reason);
}