> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# メール認証レポート：情報漏洩とOTPのJSON

> Diditのメール認証レスポンスの解析方法を解説します。OTPのライフサイクル、情報漏洩の有無、使い捨て・配信不能フラグ、セッション間の一致、リスク警告を確認できます。

メールアドレス認証レポートは、メールOTPチャレンジの結果をすべて記録します。記録されるのは、メッセージの送信先、アドレスが使い捨てか配信不能か、既知のデータ侵害に含まれているか、ユーザーの試行回数、そしてブロックリストまたは他の承認済みユーザーとのセッション間の一致です。

このページでは、判定エンドポイントが返すJSONの構造を説明します。検証済みの各アドレスについて、OTPの結果、データ侵害の有無、リスクフラグを解析する際に参照してください。

![OTPの結果、データ侵害情報、リスクフラグを表示したDiditのメールアドレス認証レポート](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/email-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4d153b7d3d9d4c88bc3932466af7ed29)

## 概要

メールレポートは、ワークフローのノードがメールアドレス認証機能を実行するたびに生成されます。各レポートは1つのアドレスに対する1回のOTPチャレンジを表し、次の内容を含みます。

* 検証された`email`アドレス。
* ブール値のリスクフラグ(`is_breached`、`is_disposable`、`is_undeliverable`)と、データ侵害インテリジェンスデータベースから取得した裏付けとなる`breaches[]`配列。
* OTP送信の試行回数(`verification_attempts`)と承認日時。
* すべての送信、再試行、コード確認の試行を時系列で記録した`lifecycle[]`ログ。
* 同じアドレスが他の承認済みメールアドレス認証やブロックリストに存在することを示す`matches[]`配列。
* 検証中に発生したリスクイベントを示す`warnings[]`配列([メールアドレス認証の警告](https://docs.didit.me/ja/core-technology/email-verification/warnings-email-verification.md)を参照)。
* レポートを生成したワークフローグラフのノードを識別する`node_id`(V3セッションのみ)。

ホスト型ワークフローセッションでは、OTPチャレンジはDiditの検証UI内で実行されるため、判定ペイロードから結果を読み取るだけで済みます。ホスト型フローを使わずにサーバー間でOTPを行う場合は、スタンドアロンのEmail APIを使用します。[`POST /v3/email/send/`](https://docs.didit.me/ja/standalone-apis/email-send)がコードを配信し、[`POST /v3/email/check/`](https://docs.didit.me/ja/standalone-apis/email-check)がユーザーの入力を検証します。確定したスタンドアロン検証も同じレポート構造で返されます。

ホスト型セッションでは、デフォルトでユーザーは**誤ったコード入力は2回まで**(`email_max_check_attempts`)、**OTP送信は2回まで(初回送信と再送信1回)**(`email_max_retries`)に制限されます。これらはワークフローノードごとに調整できます。いずれかの上限を超えると、ステップは`EMAIL_CODE_ATTEMPTS_EXCEEDED`とともに`Declined`として確定します。

## APIレスポンスでの表示箇所

判定エンドポイント(`GET /v3/session/{sessionId}/decision/`)は、メールレポートを複数形の配列キー**`email_verifications`**で返します。この配列には、ワークフローグラフ内のメールアドレス認証ノードごとに1件のエントリが含まれます。通常は1件ですが、ステップアップフローでは複数になる場合があります。

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "email_verifications": [
    { "node_id": "feature_email_1", "status": "Approved", "...": "..." }
  ]
}
```

`null`の値は、メールアドレス認証ステップがまだ実行されていないことを意味します。ワークフローで複数のメールアドレスを収集する可能性がある場合は、`email_verifications[0]`を読み取るのではなく、配列を反復処理してください。

## スキーマ

フィールドごとの正式なスキーマは[データモデル](https://docs.didit.me/ja/reference/data-models.md#メールアドレス認証)ページにあります。

```typescript theme={null}
interface EmailVerification {
  node_id: string | null;
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  email: string;
  is_breached: boolean;
  breaches: Breach[];                // Up to the 5 most recent known breaches
  is_disposable: boolean;            // Disposable / throwaway provider
  is_undeliverable: boolean;         // Failed syntax / DNS (MX) validation or OTP delivery
  verification_attempts: number;     // OTP send attempts
  verified_at: string | null;        // ISO 8601, null until a valid code is entered
  lifecycle: EmailLifecycleEvent[];  // OTP send/retry/check timeline
  warnings: Warning[];               // Risk events (see Data models → Warning object)
  matches: EmailMatch[];             // Cross-session / blocklist matches
}

interface Breach {
  name: string;                      // Breached service name
  domain: string;                    // Affected domain
  breach_date: string;               // YYYY-MM-DD
  breach_emails_count: number;       // Total affected accounts
  description: string;               // HTML description of the breach
  logo_path: string;                 // Breached-service logo URL
  data_classes: string[];            // Exposed data categories (snake_case)
  is_verified: boolean;              // true when the breach is a verified incident
}
```

配信不能なアドレス（構文が無効、ドメインが存在しない、MXレコードがない、またはOTPの配信に失敗した場合）は、自動却下の警告`UNDELIVERABLE_EMAIL_DETECTED`とともにステップを**`Declined`**として確定させます。唯一の例外は、ユーザーが自分でアドレスを入力した場合（セッション作成時に事前入力されていなかった場合）です。この場合、送信が配信不能になるとインラインエラーが返されるため、ユーザーはすぐに却下されることなく、別のアドレスで再試行できます。

### ステータス値

| ステータス | 意味 |
| - | - |
| `Not Finished` | OTPの送信は開始されていますが、認証はまだ確定していません。 |
| `Approved` | ユーザーが有効なOTPを入力し、却下につながるリスクに該当しませんでした。 |
| `Declined` | 自動却下の警告（ブロックリスト、配信不能なアドレス、試行回数超過）が発生したか、`DECLINE`に設定されたリスクアクションに該当しました。 |
| `In Review` | `REVIEW`に設定されたリスクアクションにより、ステップが手動レビューに回されました。 |
| `Expired` | 有効なコードが入力されないまま5分間のOTP有効期間が経過しました。スタンドアロンのメールAPIで作成された認証に適用されます。 |

### ライフサイクルイベントの種類

`lifecycle[]`は時系列順に並びます。各イベントには`type`、`timestamp`、`details`、および課金対象の`fee`（該当する場合）が含まれます。

| イベントの種類 | 発行されるタイミング |
| - | - |
| `EMAIL_VERIFICATION_MESSAGE_SENT` | 最初のOTP送信試行時。配信不能として返ってきた送信も含みます。 |
| `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT` | ユーザーが再送信をリクエストした後の、2回目以降のOTP送信時。 |
| `VALID_CODE_ENTERED` | ユーザーが正しいOTPコードを送信したとき。 |
| `INVALID_CODE_ENTERED` | ユーザーが誤ったOTPコードまたは期限切れのOTPコードを送信したとき（上限回数にカウントされます）。 |
| `EMAIL_VERIFICATION_APPROVED` | 機能レベルのステータスが`Approved`に設定されたとき。 |
| `EMAIL_VERIFICATION_DECLINED` | 機能レベルのステータスが`Declined`に設定されたとき。 |
| `EMAIL_VERIFICATION_IN_REVIEW` | 機能レベルのステータスが`In Review`に設定されたとき。 |
| `EMAIL_VERIFICATION_EXPIRED` | 有効なコードが入力されないままOTPの有効期間が経過したとき（スタンドアロンのメールAPI）。 |

`details`ペイロードの内容はイベントの系統によって異なります。

* **送信イベント**（`EMAIL_VERIFICATION_MESSAGE_SENT`、`EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`）: `{ status, reason }`。`status`は`Success`、`Retry`、`Undeliverable`のいずれかです。`reason`は送信に失敗した場合を除き`null`です（失敗時は`email_can_not_be_delivered`、認識できない旧形式の値の場合は`unknown`）。
* **チェックイベント**（`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`）: `{ code_tried, status }`。`status`は`Approved`、`Failed`、`Expired or Not Found`、`Declined`のいずれかです。
* **最終ステータスイベント**: `null`です。ただし`EMAIL_VERIFICATION_DECLINED`と`EMAIL_VERIFICATION_IN_REVIEW`は`{ "reason": "<risk code>" }`を持ちます（例: `UNDELIVERABLE_EMAIL_DETECTED`）。

`status`が`Success`または`Undeliverable`の送信には、\$0.02のメールアドレス認証の料金が記録されます。`Retry`の送信、チェックイベント、ステータスイベントは常に`fee: 0`です。

### セッション間の一致

`matches[]`は、同じアプリケーション内の**過去に承認された**メールアドレス認証（KYC、KYB、スタンドアロンAPIの各セッションを含む）で同じアドレスが使われた記録に加え、[Management APIのリスト](https://docs.didit.me/ja/management-api/lists/overview.md)で設定したブロックリストへの該当を記録します。現在のセッションと同じ`vendor_data`を持つ認証は除外され（同じエンドユーザーが自分自身と一致することはありません）、配列は最大**5**件で、古い順に並びます。アドレスがブロックリストに登録されているものの、一致したセッションのいずれもブロックリストに登録されていない場合は、`source: "list_entry"`を持つ合成エントリ（セッションのフィールドはすべて`null`）が配列の先頭に追加されます。

```typescript theme={null}
interface EmailMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  email: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}
```

## 例

### 承認済み: 情報レベルの違反を1件含む正常なOTP

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Approved",
  "email": "alex.sample@example.com",
  "is_breached": true,
  "breaches": [
    {
      "name": "ExampleAir",
      "domain": "example-air.com",
      "breach_date": "2022-08-25",
      "breach_emails_count": 6083479,
      "description": "In August 2022, the airline ExampleAir suffered a data breach that exposed customers' personal information.",
      "logo_path": "https://<media-host>/logos/ExampleAir.png",
      "data_classes": [
        "dates_of_birth", "email_addresses", "genders", "names",
        "nationalities", "phone_numbers", "physical_addresses",
        "salutations", "spoken_languages"
      ],
      "is_verified": true
    }
  ],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2025-09-15T17:36:19.963451Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T17:35:50.000000+00:00",
      "details": { "status": "Success", "reason": null },
      "fee": 0.02
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-09-15T17:36:19.000000+00:00",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2025-09-15T17:36:19.963451+00:00",
      "details": null,
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "BREACHED_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Breached email detected",
      "long_description": "This email address was found in one or more known data breaches.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": []
}
```

### 却下: 配信不能なアドレス

事前入力されたアドレスが構文またはDNS（MX）の検証に失敗した場合、あるいはOTPメールを配信できなかった場合は、ただちに`Declined`として確定します。コードがユーザーに届いていないため、コードチェックのイベントは表示されません。

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Declined",
  "email": "user@nonexistent-domain.example",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": true,
  "verification_attempts": 1,
  "verified_at": null,
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T18:00:00.000000+00:00",
      "details": { "status": "Undeliverable", "reason": "email_can_not_be_delivered" },
      "fee": 0.02
    },
    {
      "type": "EMAIL_VERIFICATION_DECLINED",
      "timestamp": "2025-09-15T18:00:01.500000+00:00",
      "details": { "reason": "UNDELIVERABLE_EMAIL_DETECTED" },
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "UNDELIVERABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Undeliverable email detected",
      "long_description": "The system detected that the email is undeliverable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": []
}
```

### 却下: ブロックリストに登録された使い捨てメールアドレス

ユーザーはOTPによる認証を完了しましたが、アドレスがメールのブロックリストに一致しました（自動却下）。使い捨てメールのフラグも立っていますが、ここでは`disposable_email_action`がデフォルトの`NO_ACTION`のままのため、`information`レベルになっています。

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Declined",
  "email": "user@mailinator.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": true,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2025-09-15T18:05:42.201734Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T18:05:01.000000+00:00",
      "details": { "status": "Success", "reason": null },
      "fee": 0.02
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-09-15T18:05:42.000000+00:00",
      "details": { "code_tried": "654321", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_DECLINED",
      "timestamp": "2025-09-15T18:05:42.201734+00:00",
      "details": { "reason": "EMAIL_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "EMAIL_IN_BLOCKLIST",
      "additional_data": {
        "blocklisted_session_id": null,
        "blocklisted_session_number": null,
        "api_service": null
      },
      "log_type": "error",
      "short_description": "Email in blocklist",
      "long_description": "The system detected that the email is in the blocklist, which is not allowed.",
      "node_id": "feature_email_1"
    },
    {
      "feature": "EMAIL",
      "risk": "DISPOSABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Disposable email detected",
      "long_description": "The system detected that the email is disposable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "email": "user@mailinator.com",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ]
}
```

## 関連情報

* [メールアドレス認証の概要](https://docs.didit.me/ja/core-technology/email-verification/overview.md): 機能の動作と料金。
* [メールアドレス認証の警告](https://docs.didit.me/ja/core-technology/email-verification/warnings-email-verification.md): すべてのリスクコード、却下のトリガー、設定可能なアクション。
* [データモデル: メールアドレス認証](https://docs.didit.me/ja/reference/data-models.md#メールアドレス認証): フィールドごとの正式なスキーマ。
* [メールAPI: OTPの送信](https://docs.didit.me/ja/standalone-apis/email-send.md)と[OTPの確認](https://docs.didit.me/ja/standalone-apis/email-check.md): 独立して使用できるサーバー間エンドポイント。
* [Management API: リスト](https://docs.didit.me/ja/management-api/lists/overview.md): `source: list_entry`を含む`matches[]`に使用されるメールアドレスのブロックリストを管理します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.