新機能「Email Address Validation API」のご紹介

新機能「Email Address Validation API」のご紹介
先日のブログでもお知らせした通り、弊社（株式会社構造計画研究所）でご契約いただいたTwilio SendGridアカウントでは、4月1日から新しい機能群が利用できるようになりました。今回は、その新機能の中から「Email Address Validation API」を紹介します。

Email Address Validation APIとは？

Email Address Validation APIは、メールを実際に送信することなくメールアドレスの有効性を検証することができるAPIです（Pro以上のプランでのみ利用可能）。メールアドレスの入力ミスや、宛先ドメインのメールサーバの有無、過去のバウンス歴などを調べることができます。

このAPIには、1つのメールアドレスの検証結果をリアルタイムで返すエンドポイントと、宛先リストのCSVファイルをアップロードすることで非同期に検証を行い、結果をCSVで取得できるエンドポイントがあります。前者はフォーム入力時のリアルタイム検証に、後者は既存の宛先リストのクリーニングに活用できます。

使い方

ここからは、実際に試しながら機能を紹介していきます。

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

APIキーの作成

まずはSendGridのダッシュボードからAPIキーを作成しましょう。他のAPIを利用する場合と異なり、Email Address Validation API専用のAPIキーを作成する必要があるので注意してください。

SendGridダッシュボードのSettingsの「API Keys」を選択し、右上の「Create API Key」をクリックすると以下のような画面が表示されます。

APIキーの作成
「API Key Name」に適当な名前を入力し、「API Key Permissions」の選択肢の中から「Email Address Validation Access」を選びましょう。「Access Details」の「Validation」の項目を「Full Access」にし、「Create & View」ボタンをクリックするとAPIキーが表示されます。後から確認し直すことができないので、セキュアな場所に保存しておいてください。

リクエストとレスポンス

次に、作成したAPIキーを用いてリクエストを行います。以下はcURLで「sendgridtesting@gmail.com」を検証するリクエストの例です。

curl -X POST "https://api.sendgrid.com/v3/validations/email" \
--header "Authorization: Bearer <<API_KEY>>" \
--header "Content-Type: application/json" \
--data '{
  "email": "sendgridtesting@gmail.com",
  "source": "signup"
}'

すると、以下のようなレスポンスが返ってきます。

{
  "result": {
    "email": "sendgridtesting@gmail.com",
    "verdict": "Valid",
    "score": 0.87351,
    "local": "sendgridtesting",
    "host": "gmail.com",
    "checks": {
      "domain": {
        "has_valid_address_syntax": true,
        "has_mx_or_a_record": true,
        "is_suspected_disposable_address": false
      },
      "local_part": {
        "is_suspected_role_address": false
      },
      "additional": {
        "has_known_bounces": false,
        "has_suspected_bounces": false
      }
    },
    "source": "SIGNUP",
    "ip_address": "192.0.2.1"
  }
}

重要な指標をいくつか抜粋して説明すると以下の通りです。

verdict：検証の総合評価（Valid、Risky、Invalidの三段階）
score：評価を0〜1の数値で表したもの
has_valid_address_syntax：メールアドレスの形式が正しいかどうか
has_mx_or_a_record：宛先ドメインにメールサーバ（MXレコードもしくはAレコード）があるかどうか
has_known_bounces：過去にSendGridプラットフォームからの送信でバウンスした履歴があるかどうか

上のケースでは有効（Valid）と判定され、scoreも0.87と高いことがわかります。
has_valid_address_syntaxやhas_mx_or_a_recordがfalseの場合はメールが届けられないことが確実なので、verdictはInvalid、scoreは0となります。これらの検証結果をうまく活用することで、届かない宛先へのメール送信を未然に防ぎ、バウンス率を低く保つことが可能です。

verdictやscoreはわかりやすい指標ではありますが、SendGrid独自のアルゴリズムに基づいているため根拠が予想しづらい場合があります。初めはhas_mx_or_a_record等の確実な指標から利用し、実際の評価（verdict）やスコアをダッシュボード（後述）等で見極めつつ、組み込みを検討すると良いでしょう。

また、ドメインに入力ミスがあると疑われる場合は、suggestionで正しいと思われるドメインをお知らせします。例えばドメインが”gmal.com”（「gmail.com」のiが抜けている）のメールアドレスを指定すると以下のようなレスポンスになります。

{
  "result": {
    "email": "sendgridtesting@gmal.com",
    "verdict": "Invalid",
    "score": 0,
    "local": "sendgridtesting",
    "host": "gmal.com",
    "suggestion": "gmail.com",
    "checks": {
      "domain": {
        "has_valid_address_syntax": true,
        "has_mx_or_a_record": false,
        "is_suspected_disposable_address": false
      },
      "local_part": {
        "is_suspected_role_address": false
      },
      "additional": {
        "has_known_bounces": false,
        "has_suspected_bounces": false
      }
    },
    "source": "SIGNUP",
    "ip_address": "192.0.2.1"
  }
}

suggestionに正しいドメイン「gmail.com」が表示されていることがわかります。WebサイトのフォームにAPIを組み込めば、レスポンスにsuggestionが含まれていた場合に警告を表示させるといった応用が可能です。

ダッシュボードでの確認

リアルタイム検証APIの結果は、ダッシュボードの「Validation」メニューからも確認できます。verdictの評価、scoreの値、リクエスト時に指定したsourceパラメータ等でフィルタリングできるほか、CSV出力も可能なので、API利用状況の確認や、検証結果の傾向の把握にお役立てください。

② 複数の宛先のバッチ処理

こちらのAPIでは、CSV形式もしくはそれをZIPに圧縮したファイルにメールアドレスをまとめ、指定のURLにアップロードすると、バッチ処理を行って検証結果を非同期でお知らせします。APIキーの作成手順は単一のメールアドレスの検証と同じですが、その後のリクエストの流れが異なります。

CSVファイルの用意

まず「emails」をヘッダに指定した単一カラムのCSVを用意します。

emails
john-doe@example.com
jane.doe@example.co.jp
sendgridtesting@gmil.com

アップロード

次にアップロードしたいファイルの形式（CSVもしくはZIP）をfile_typeパラメータで指定してPUTリクエストを行います。

curl -X PUT "https://api.sendgrid.com/v3/validations/email/jobs" \
--header "Authorization: Bearer <<API_KEY>>" \
--header "Content-Type: application/json" \
--data '{"file_type": "csv"}'

{
  "job_id":"Q6EMJAPNSPGHNV204C1XM0V4P2",
  "upload_uri":"https://example.com/unique-url-from-the-put-request",
  "upload_headers":
    [
      {"header":"x-amz-server-side-encryption","value":"aws:kms"},
      {"header":"content-type","value":"text/csv"}
    ]
}

レスポンスにはアップロードURLとそのリクエスト時に必要なHTTPヘッダが返されるので、それらを指定してファイルをアップロードします。

curl --upload-file "./path/to/your/fileForUpload.csv" \ 
"https://example.com/unique-url-from-the-put-request" \
--header "x-amz-server-side-encryption: aws:kms" \
--header "content-type: text/csv"

結果の取得

しばらく待つとアカウントの登録メールアドレスに「Your Email Address Validation export」というメールが届き、メール内のDownloadボタンをクリックすると結果のファイルがダウンロードされます。この時、必ずSendGridダッシュボードにログインした状態でクリックしてください。結果のCSVファイルに記載される内容は、基本的に単一の宛先検証の結果と同じです。

既存の宛先リストに対して検証を行えば、特定の条件（VerdictがInvalidになっている等）に合致する宛先を抽出してリストから取り除くことができ、送信通数の削減やバウンスの予防が可能です。

さいごに

Email Address Validation APIは、入力ミスと思われるメールアドレスがフォームに入力されたら修正を促したり、形式は正しいが届かない宛先がフォームに入力された際にメール送信しないようにしたり、既存の宛先リストに送信する前にリストクリーニングを行ったりと、様々な活用方法があります。Pro以上のプランでは2,500アドレスまで無料で利用できるので、ぜひご活用ください。

利用方法の詳細は以下のドキュメントとAPIリファレンスをご参照ください。

単一の宛先のリアルタイム検証：ドキュメント、APIリファレンス
複数の宛先のバッチ処理：ドキュメント、APIリファレンス

次回は、単一の宛先検証APIを使って、メールアドレスの入力ミスを指摘するフォームの実用例を紹介します。こちらもぜひご覧ください。

検索

カテゴリ

アーカイブ

メールを成功の原動力に

開発者にもマーケターにも信頼されているメールサービスを利用して、
時間の節約、スケーラビリティ、メール配信に関する専門知識を手に入れましょう。