単一の宛先のリアルタイム検証

単一の宛先を検証するAPIでは、リクエストパラメータで指定したメールアドレスの有効性を検証してリアルタイムに結果を返します。複数の宛先を一括で検証したい場合は、「複数の宛先のバッチ検証」をご利用ください。

利用方法

専用のAPIキーの作成

Email Address Validation APIを利用するには、専用のAPIキーを作成する必要があります。「Full Access」のAPIキーは利用できません。

Email Address Validation APIはPro以上のアカウントでのみ利用可能です。Free/Essentialsプランのアカウントでは、専用のAPIキーを作成できません。

  1. Settings > API Keys を選択し、右上の「Create API Key」をクリックします。
  2. 「API Key Name」に任意の名前を入力し、「API Key Permissions」の「Email Address Validation Access」を選択します。
  3. 「Validation」の右側にある「Full Access」を選択します。
  4. 「Create & View」ボタンをクリックします。
  5. 表示されたAPIキーをコピーし、安全な場所に保存します。セキュリティの観点から、APIキーは1度しか表示されず、再確認することはできません。

Email Address Validation Accessを選択してAPIキーを作成する

利用の注意点

作成したAPIキーを用い、1つのメールアドレスを指定してPOSTリクエストを行うと、JSON形式のレスポンスで評価と詳細なデータを返します。エンドポイントの詳細な情報はAPIリファレンスを参照してください。

利用の際は、以下の点に留意してください。

  • 一度に複数のメールアドレスは受け付けられません。
  • APIエンドポイントの呼び出し制限は7リクエスト/秒です。
  • JavaScript等で書かれたクライアントサイドから直接本APIを呼び出さないでください。APIキーがクライアントサイドのコードに記述されていると、第三者によりAPIを不正利用される恐れがあります。クライアントサイドでフォーム送信した後等に、アプリケーションのバックエンドでAPIを呼び出してください。
  • Webフォームに本APIを組み込む場合は、メールアドレスの検証結果によらず、Webサイト訪問者がフォーム送信できる余地を残してください。
  • リクエストでオプションのsourceパラメータを指定すると、指定した値がSendGridからのレスポンスに含まれる他、後述するダッシュボードに記載されます。これは本APIをどこから呼び出したかを区別するのに利用できます。

sourceパラメータの種類はアカウントあたり50までという上限があります。sourceは、そのsourceを指定して最後にリクエストを行ってから30日を過ぎると自動的に削除されます。

APIレスポンスの概要

Email Address Validation APIは、機械学習モデルを活用した検証を行い、結果を返します。メーリングリストから正当なメールアドレスを誤って除外したりブロックしたりしないよう、偽陰性（有効なアドレスを無効と判定すること）の割合を低く抑えるよう調整されています。主要なレスポンスパラメータを抜粋して以下に説明します。

Verdict（評価）

このフィールドには、”Valid”、”Risky”、”Invalid”のいずれかが入ります。これらは検証結果を総合的に判断し、三段階評価で分類したものです。

Score

メールアドレスが有効である可能性を0から1の数値で表しています。例えば、スコアが0.96の場合は、メールアドレスが有効である可能性が96%であることを示します。Verdictフィールドの三段階評価よりも細かい制御が必要な場合は、このスコアに基づいて閾値を設定できます。

Checks

このフィールドには、メールアドレスに対して実行されたすべてのチェック項目とその結果が記載されます。

  • has_valid_address_syntax
    trueの場合、適切な形式のメールアドレスです（@記号とトップレベルドメインがある）。falseの場合は不正な形式のアドレスです。
  • has_mx_or_a_record
    trueの場合、アドレスのドメイン部分には配信先を指すためのDNSレコード（MXレコードもしくはAレコード）が存在します。falseの場合は、必要なDNSレコードが存在しないため、送信してもバウンスします。
  • is_suspected_disposable_address
    trueの場合、アドレスのドメイン部が一時的な利用を目的とした使い捨てメールアドレスサービスのものと疑われます。
  • is_suspected_role_address
    trueの場合、アドレスのローカルパート（@記号より前）がメーリングリストのものと疑われます（hrやadminなど）。
  • has_known_bounces
    trueの場合、このアドレスは過去にSendGridプラットフォームからの送信でバウンスしています。
  • has_suspected_bounces
    trueの場合、機械学習モデルによりこのアドレスはバウンスする可能性があると判断しています。

例えば、Scoreが低くても使い捨てアドレスにはメールを送信したい、という場合はこのフィールドを利用してフィルタリングできます。

Suggestion

メールアドレスのドメイン部にタイプミスが疑われる場合、正しいと思われるドメインを提案します。

例えば、「john.doe@gmial.com」を検証した場合、レスポンスに「gmail.com」というsuggestionが含まれる可能性があります。この提案をローカルパート（john.doe）と組み合わせて、本来の意図したアドレス「john.doe@gmail.com」を構成できます。

ダッシュボードの概要

ダッシュボードの「Validation」にアクセスすると、このAPIで過去30日間に検証したメールアドレスの結果が確認できます。APIを呼び出した日にち、評価（Verdict）、リクエスト時に指定したsourceパラメータ、スコアのパーセンテージでフィルタリングが可能です。

過去30日間の検証結果の表示

結果の詳細の表示

ダッシュボードで特定のメールアドレスを選択すると、そのアドレスの詳細な検証結果を見ることができます。

検証結果の詳細の表示

結果のエクスポート

「Export CSV」ボタンからCSVリストをエクスポートできます。例えば、有効と判定した連絡先をSendGridのマーケティングキャンペーン機能や、自社のデータベース、CRMなどにアップロードするのに活用できます。