Email Address Validation API

Email Address Validation APIでは、次の機能を利用できます。

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

複数の宛先のバッチ検証

Email Address Validation APIはPro以上のプランで利用可能です。

また、「Email Address Validation Access」の権限を持つAPIキーを利用する必要があります。APIキーの作成方法はこちらをご覧ください。

Real Time Email Address Validation

Real Time Email Address Validation [POST]

単一のメールアドレスの有効性を検証してリアルタイムに結果を返します。機能の説明はこちらをご参照ください。

Request

1

POST https://api.sendgrid.com/v3/validations/email HTTP/1.1

Request body

JSONパラメータ 型 必須 制限 詳細
email string Yes メールアドレス
検証対象のメールアドレス
source string No 半角英数字、スペース
呼び出し元を識別するための文字列（活用方法はこちら
）		 
1
2
3
4

{
  "email": "example@example.com",
  "source": "signup"
}

Response

JSONパラメータ 型 制限 詳細
result オブジェクト
検証結果
email string メールアドレス
検証対象のメールアドレス
verdict string Valid、Risky、Invalidのいずれか
検証結果の分類
score number 0～1の間
メールアドレスの有効性を数値で表したもの
local string
メールアドレスのローカルパート（@より前の文字列）
host string
メールアドレスのドメイン（@より後の文字列）
suggestion string
ドメインにタイプミスがあると思われる場合に返される修正候補
checks オブジェクト
より詳細な検証結果
domain オブジェクト
ドメインの検証結果
has_valid_address_syntax boolean
メールアドレスの形式が正しいかどうか
has_mx_or_a_record boolean
メールを受信するための適切なDNSレコードが登録されているかどうか
is_suspected_disposable_address boolean
使い捨てメールアドレスサービスのドメインかどうか
local_part オブジェクト
ローカルパートの検証結果
is_suspected_role_address boolean
ローカルパートからロールやグループアカウントと推定されるかどうか（例：admin、info）
additional オブジェクト
その他の検証結果
has_known_bounces boolean
SendGridプラットフォームからの送信でバウンスした履歴があるかどうか
has_suspected_bounces boolean
SendGridの機械学習モデルから推定した、バウンスが発生する可能性の有無
source string 半角英数字、スペース
リクエスト時に指定したsource
ip_address string
検証をリクエストした環境のIPアドレス 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

HTTP/1.1 200
{
  "result": {
      "email": "example@example.com",
      "verdict": "Valid",
      "score": 0.79798,
      "local": "example",
      "host": "example.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": "198.51.100.1"
  }
}

Bulk Email Address Validation

最大100万件のメールアドレスの有効性を非同期で一括検証できます。Bulk Email Address Validationの詳細な利用方法については、こちらをご参照ください。

Request a Bulk Email Address Validation Upload URL [PUT]

検証するメールアドレスリストのアップロードに必要な、署名付きURLとリクエストヘッダを取得します。

Request

1

PUT https://api.sendgrid.com/v3/validations/email/jobs HTTP/1.1

Request Body

JSONパラメータ 型 必須 制限 詳細
file_type string Yes csvもしくはzip
アップロードするファイルの形式 
1
2
3

{
  "file_type": "csv"
}

Response

JSONパラメータ 型 制限 詳細
job_id string
一意のジョブID
upload_uri string
メールアドレスリストのアップロードリクエストに使用するURI
upload_headers オブジェクト配列
アップロードリクエストに必要なヘッダの一覧
header string
アップロードリクエストに必要なヘッダの名前
value string
アップロードリクエストに必要なヘッダの値 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

HTTP/1.1 200
{
    "job_id": "01HW43JJPNKJQFQZJCGXRV547Y",
    "upload_uri": "https://evbulkupload-prod-us-east-2-emails-csv.s3.us-east-2.amazonaws.com/…",
    "upload_headers": [
        {
            "header": "content-type",
            "value": "text/csv"
        },
        {
            "header": "x-amz-server-side-encryption",
            "value": "aws:kms"
        }
    ]
}

得られたレスポンスを使ってメールアドレスリストをアップロードする方法はこちらをご覧ください。

Get Bulk Email Address Validation Jobs [GET]

Bulk Email Address Validationのジョブ一覧を取得します。

Request

1

GET https://api.sendgrid.com/v3/validations/email/jobs HTTP/1.1

Response

JSONパラメータ 型 制限 詳細
result オブジェクト配列
各ジョブの処理状況情報
id string
一意のジョブID
status string Initiated、Queued、Ready、Processing、Done、Errorのいずれか
ジョブのステータス
started_at number UNIXタイムスタンプ
ジョブが作成された（upload_uriにアップロードリクエストが送られた）時刻
finished_at number UNIXタイムスタンプ
ジョブが終了した時刻 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

HTTP/1.1 200
{
    "result": [
        {
            "id": "01HW43JJPNKJQFQZJCGXRV547Y",
            "status": "Initiated",
            "started_at": 0,
            "finished_at": 0
        },
        {
            “id”: "01JTTBVEE0DC2M98VPS1RBP3CR",
            “status”: “Queued”,
            "started_at": 1713831030,
            "finished_at": 0
        {
            "id": "01HW4QDY4VMS3TEMPS7PEWAGDD",
            "status": "Done",
            "started_at": 1713851241,
            "finished_at": 1713851287
        }
    ]
}

Get a Bulk Email Address Validation Job by ID [GET]

指定したジョブの進行状況に関する情報を取得します。

検証結果のダウンロードURLは、検証完了後にアカウントの登録メールアドレス宛にメールで通知されます。このエンドポイントで直接取得することはできません。

URI引数 必須 条件 説明
job_id Yes string ジョブID

Request

1

GET https://api.sendgrid.com/v3/validations/email/jobs/{job_id} HTTP/1.1

Response

JSONパラメータ 型 制限 詳細
result オブジェクト
指定したジョブの情報
id string
ジョブID
status string Initiated、Queued、Ready、Processing、Done、Errorのいずれか
ジョブのステータス
segments number
ジョブを並列処理するために分割されたセグメント数。1セグメントあたり1,500件のメールアドレスが含まれ、最大で100セグメントが並列処理される。statusがProcessingになるまでは0が返される。
segments_processed number
リクエスト実行時点で処理されたセグメントの数。
is_download_available boolean
結果のCSVファイルがダウンロード可能かどうか
started_at number UNIXタイムスタンプ
ジョブが作成された（upload_uriにアップロードリクエストが送られた）時刻
finished_at number UNIXタイムスタンプ
ジョブが終了した時刻
errors オブジェクト配列
エラー情報。エラーがない場合、配列は空。
message string
ジョブの実行中に発生したエラーの内容 
1
2
3
4
5
6
7
8
9
10
11
12
13

HTTP/1.1 200
{
  "result": {
      "id": "01HW43JJPNKJQFQZJCGXRV547Y",
      "status": "Done",
      "segments": 1,
      "segments_processed": 1,
      "is_download_available": true,
      "started_at": 1713831030,
      "finished_at": 1713831188,
      "errors": []
  }
}