Email Verification Warnings

The Email Verification feature emits warnings whenever a risk signal fires on the OTP flow or the address itself: a known data breach, a disposable provider, an undeliverable mailbox, an OTP attempt cap, or a hit against your blocklist or another approved verification. This page lists every code, what triggers it, and how to configure the workflow response.

Overview

Warnings are tagged with feature EMAIL. They appear on the report under email_verifications[].warnings[] and follow the standard warning object shape (feature, risk, additional_data, log_type, short_description, long_description, node_id). Each warning is also routed into the per-session log so it surfaces in the Business Console under the Email section. Some warnings are hard auto-decline triggers — they always set the feature status to Declined and carry log_type: "error". The others map to a configurable action (DECLINE, REVIEW, or the default NO_ACTION) defined per workflow node or per API call, so the same risk code may decline one workflow while only flagging another. The configured action also sets the severity: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Auto-decline conditions

The following warnings always decline the Email Verification step regardless of configuration:

EMAIL_CODE_ATTEMPTS_EXCEEDED — the user exhausted the OTP budget: 2 wrong code entries (email_max_check_attempts) or 2 OTP sends — the initial send plus one resend (email_max_retries) — by default.
EMAIL_IN_BLOCKLIST — the address is in a blocklist managed via the Lists API, or matched a previously approved email verification that was blocklisted.
UNDELIVERABLE_EMAIL_DETECTED — the address cannot receive mail: invalid syntax, a non-existent domain, missing DNS (MX) records, or the OTP email could not be delivered. The step finalizes as Declined immediately — no code check ever runs. Exception: when the user typed the address themselves (it was not pre-filled at session creation), an undeliverable send returns an inline error so they can retry with a different address instead of being declined.

Configurable risks

Each of the following risks maps to a setting (per workflow node, or per call on the standalone check endpoint) you can configure to DECLINE, REVIEW, or NO_ACTION:

Setting	Risk code	Default behavior
`breached_email_action`	`BREACHED_EMAIL_DETECTED`	`NO_ACTION` — surface breach details at `information` level without changing the status.
`disposable_email_action`	`DISPOSABLE_EMAIL_DETECTED`	`NO_ACTION` — flag the throwaway provider at `information` level without changing the status.
`duplicated_email_action`	`DUPLICATED_EMAIL`	`NO_ACTION` — record the duplicate at `information` level. Skipped when the address is allowlisted.

Duplicate detection only considers previously approved email verifications in the same application, grouped by vendor_data — verifications sharing the same vendor_data are treated as one end-user and excluded. Leave vendor_data empty and every session is treated as a distinct user. If the address is on your email allowlist, the duplicate action is skipped and EMAIL_IN_ALLOWLIST is emitted instead.

Verification attempt limits

The Email Verification feature applies a hard cap on OTP attempts to prevent abuse:

Code-entry attempts — email_max_check_attempts, default 2: the second wrong (or expired) code finalizes the step.
Send attempts — email_max_retries, default 2 sends in total (the initial send plus one resend): a further resend request finalizes the step.

Exceeding either cap raises EMAIL_CODE_ATTEMPTS_EXCEEDED and auto-declines. You can tune both caps per workflow node.

Warnings produced

Tag	Severity	Description
`EMAIL_CODE_ATTEMPTS_EXCEEDED`	`error`	The user exceeded the code-entry or send cap. Auto-declines.
`EMAIL_IN_BLOCKLIST`	`error`	The address is present in a blocklist created via the Lists API, or matched a blocklisted approved verification. Auto-declines. `additional_data` carries `blocklisted_session_id`, `blocklisted_session_number` and `api_service` (all `null` for a pure list hit).
`EMAIL_IN_ALLOWLIST`	`information`	The address matched an allowlist created via the Lists API, so the duplicate-email action was skipped.
`BREACHED_EMAIL_DETECTED`	Per `breached_email_action` (`information` by default)	The address was found in one or more known data breaches. The `breaches[]` array on the report carries the breached service, date and data classes.
`DISPOSABLE_EMAIL_DETECTED`	Per `disposable_email_action` (`information` by default)	The domain is a known disposable / throwaway provider often used to evade traceability.
`UNDELIVERABLE_EMAIL_DETECTED`	`error`	The address cannot receive mail (invalid syntax, non-existent domain, missing MX records, or failed delivery). Auto-declines.
`DUPLICATED_EMAIL`	Per `duplicated_email_action` (`information` by default)	The address matches a previously approved email verification belonging to a different end-user (grouped by `vendor_data`). `additional_data` carries `duplicated_session_id`, `duplicated_session_number` and `api_service`.

At most one of EMAIL_IN_BLOCKLIST, DUPLICATED_EMAIL and EMAIL_IN_ALLOWLIST fires per attempt — blocklist takes precedence over duplicate, which takes precedence over allowlist.

Cross-session matches

When an address is detected on previously approved email verifications or on your blocklist, those hits also appear under email_verifications[].matches[] (capped at 5 entries). Each match carries session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, and a source of session (another approved verification) or list_entry (a blocklist entry). If the current address is on your email allowlist, Didit keeps the match evidence but emits EMAIL_IN_ALLOWLIST instead of applying the duplicate-email action. See the Email Verification report for the full match schema.

Example

{
  "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"
    }
  ]
}

Warning types

Each risk is assigned a severity based on your application’s configuration. Severities fall into three categories:

Email Verification overview — feature behavior and pricing.
Email Verification report — full response shape including lifecycle[] and matches[].
Data models — email verification — canonical field-by-field schema.
Management API — Lists — manage the email blocklist used by EMAIL_IN_BLOCKLIST.

Authentication

Verification

Monitoring

Platform

Overview

Auto-decline conditions

Configurable risks

Verification attempt limits

Warnings produced

Cross-session matches

Example

Warning types

​Overview

​Auto-decline conditions

​Configurable risks

​Verification attempt limits

​Warnings produced

​Cross-session matches

​Example

​Warning types

​Related

Overview

Auto-decline conditions

Configurable risks

Verification attempt limits

Warnings produced

Cross-session matches

Example

Warning types

Related