> ## 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-проверки по email: кому было отправлено сообщение, является ли адрес одноразовым или недоставляемым, фигурирует ли он в известных утечках данных, сколько попыток потребовалось пользователю, а также любые межсессионные совпадения с вашим списком блокировки или другими одобренными пользователями.

На этой странице описана структура JSON, возвращаемая endpoint решения, что позволяет анализировать результаты OTP, наличие адреса в утечках и флаги риска для каждого проверенного адреса.

![Didit email verification report showing OTP outcome, breach data and risk flags](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)

## Обзор

Отчёт по email формируется каждый раз, когда узел сценария выполняет функцию «Проверка электронной почты». Каждый отчёт представляет одну OTP-проверку для одного адреса и содержит:

* Проверенный адрес `email`.
* Логические флаги риска (`is_breached`, `is_disposable`, `is_undeliverable`) и подтверждающий массив `breaches[]`, полученный из базы данных об утечках.
* Количество попыток отправки OTP (`verification_attempts`) и временную метку одобрения.
* Хронологический журнал `lifecycle[]` для каждой отправки, повторной попытки и попытки проверки кода.
* Массив `matches[]`, отображающий тот же адрес в других одобренных проверках электронной почты или в вашем списке блокировки.
* Массив `warnings[]` — события риска, зафиксированные в ходе верификации (см. раздел [Предупреждения Проверки электронной почты](https://docs.didit.me/ru/core-technology/email-verification/warnings-email-verification.md)).
* Идентификатор `node_id`, указывающий, какой узел графа сценария сформировал отчёт (только для сессий V3).

В размещённых сессиях сценария OTP-проверка выполняется внутри интерфейса верификации Didit — вы только считываете результат из payload решения. Для межсерверной OTP-проверки без размещённого сценария используйте отдельный Email API: [`POST /v3/email/send/`](https://docs.didit.me/ru/standalone-apis/email-send) доставляет код, а [`POST /v3/email/check/`](https://docs.didit.me/ru/standalone-apis/email-check) проверяет ввод пользователя; завершённые отдельные верификации возвращаются в той же структуре отчёта.

По умолчанию в размещённых сессиях для пользователя установлено ограничение в **2 неверные попытки ввода кода** (`email_max_check_attempts`) и **2 отправки OTP — начальная отправка плюс одна повторная** (`email_max_retries`), настраиваемое для каждого узла сценария. Превышение любого из этих лимитов завершает шаг со статусом `Declined` и причиной `EMAIL_CODE_ATTEMPTS_EXCEEDED`.

## Где он появляется в ответах API

Endpoint решения (`GET /v3/session/{sessionId}/decision/`) возвращает отчёты по email в массиве под ключом во множественном числе **`email_verifications`**. Массив содержит по одной записи для каждого узла Проверки электронной почты в графе сценария — обычно одну, но сценарии с усиленной проверкой могут создавать несколько.

```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/ru/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 — переводит шаг в статус **`Declined`** с предупреждением об автоматическом отклонении `UNDELIVERABLE_EMAIL_DETECTED`. Единственное исключение: если пользователь ввёл адрес самостоятельно (он не был предварительно заполнен при создании сессии), неудачная отправка возвращает встроенную ошибку, позволяя повторить попытку с другим адресом вместо немедленного отклонения.

### Значения статуса

| Статус | Значение |
| - | - |
| `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` | Последующая отправка OTP после того, как пользователь запросил повторную отправку. |
| `VALID_CODE_ENTERED` | Пользователь ввёл правильный код OTP. |
| `INVALID_CODE_ENTERED` | Пользователь ввёл неправильный или просроченный код 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/ru/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
}
```

## Примеры

### Одобрено — корректный 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, но адрес совпал с вашим списком блокировки электронной почты (автоотклонение). Также выставлен флаг одноразовой почты — здесь на уровне `information`, поскольку для `disposable_email_action` оставлено значение по умолчанию `NO_ACTION`.

```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/ru/core-technology/email-verification/overview.md) — работа функции и цены.
* [Предупреждения Проверки электронной почты](https://docs.didit.me/ru/core-technology/email-verification/warnings-email-verification.md) — все коды рисков, триггеры отклонения и настраиваемые действия.
* [Модели данных — проверка электронной почты](https://docs.didit.me/ru/reference/data-models.md#проверка-электронной-почты) — каноническая схема полей.
* [Email API — Send OTP](https://docs.didit.me/ru/standalone-apis/email-send.md) и [Check OTP](https://docs.didit.me/ru/standalone-apis/email-check.md) — автономные endpoints межсерверного взаимодействия.
* [Management API — Lists](https://docs.didit.me/ru/management-api/lists/overview.md) — управление списком блокировки электронной почты, который передаётся в `matches[]` с `source: list_entry`.


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