複数の宛先のバッチ検証

このAPIでは、100万件までのメールアドレスを非同期で一括検証できます。リアルタイム検証APIは1秒あたり7回のリクエスト（7つのメールアドレス）という制限がありますが、このAPIは1秒あたり概ね350件のメールアドレスを検証でき、既存の宛先リストのクリーンアップに最適です。

利用方法

PUTリクエストにより取得できるURLに、メールアドレスを含むCSVファイル（もしくはCSVファイルを圧縮したZIPファイル）をアップロードすると、SendGridが非同期で検証を行います。その後、アカウントの登録メールアドレスに結果が記載されたCSVファイルのダウンロードURLが送信されます。

検証結果には、三段階の評価や数値スコア、チェック項目の詳細が含まれます。

専用のAPIキーの作成

まず、必要な権限を持ったAPIキーの作成が必要です。詳細はリアルタイム検証APIのドキュメントを参照してください。なお、GETリクエストを行うには「Reporting」のRead Accessが必要です。

CSVファイルの準備

メールアドレスのリストをCSV形式で作成します。以下の例のように、先頭行に”emails”という列名を付け、検証するメールアドレスのみを含めてください。アップロードは、CSV形式もしくはそれをZIP形式に圧縮したものを指定可能です。含まれるメールアドレスの件数は100万件までで、かつファイルサイズが50MB未満である必要があります。

1
2
3
4
5

emails
test@exampledomain.com
test2@exampledomain.com
differentTest@differentexampledomain.com
lastEmail@lastexampledomain.net

アップロード用URLの取得

APIエンドポイントにPUTリクエストを送ることで、アップロード用のURLとアップロードのリクエスト時に必要なHTTPヘッダを取得できます。 このリクエスト時にパラメータとして指定するfile_typeは、アップロードするファイルタイプ（”csv”もしくは”zip”）と一致している必要があります。

レスポンスに含まれるjob_idを保存すれば、後から検証の進捗状況を確認することができます。

ファイルのアップロード

PUTリクエストのレスポンスに含まれるupload_uriとrequest_headersを使って、CSVファイルまたはZIPファイルをアップロードするリクエストを送信します。以下はcURLでアップロードする例です。

1
2
3
4

curl --upload-file "./path/to/your/fileForUpload.csv" \
"https://example.com/the-upload-uri-from-the-put-request" \
-H "x-amz-server-side-encryption: aws:kms" \
-H "content-type: text/csv"
  • ./path/to/your/fileForUpload.csvにはCSVまたは.zipファイルへの相対パスを指定します
  • https://example.com/the-upload-uri-from-the-put-requestのURLには、PUTリクエストで取得したアップロード用URL（upload_uri）を指定します
  • x-amz-server...およびcontent-type: txt/csvには、request_headersパラメータで指定されたヘッダを指定します

アップロードに失敗すると、アップロード先（AWS）からエラー（通常はSignature Does Not Match）が返されます。このようなエラーが出た場合は、cURLリクエストの形式に問題があります。余分な”\”や引用符の不一致がないか、指定したURLやヘッダが得られたレスポンスの文字列と一致しているかを確認してください。

アップロードリクエストが成功すると、空のレスポンスボディが返されます。検証プロセスの進捗状況は、PUTリクエストで得られたjob_idに対してGETリクエストを送ることで確認できます。job_idを指定せずにGETリクエストを行うと、すべてのジョブの一覧を取得できます。

結果のダウンロード

検証が完了すると、アカウントの登録メールアドレス宛に検証結果を取得するためのメールが送られます。アカウントにログインした状態でメール内の「Download」ボタンを押すと、検証結果のCSVファイルがダウンロードされます。

検証結果の概要

CSVファイルには検証対象の各メールアドレスについて以下の項目が記載されます。各項目の内容は、APIリファレンスおよびリアルタイム検証APIのドキュメントの対応する項目を参照してください。

  • Verdict
  • Score
  • Local
  • Host
  • Suggestion
  • HasValidAddressSyntax
  • HasMXorARecord
  • IsSuspectedDispsableAddress
  • IsSuspectedRoleAddress
  • HasKnownBounces
  • HasSuspectedBounces