> ## 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. # Report di verifica email: JSON violazioni e OTP > Analizza i report di verifica email di Didit: ciclo di vita OTP, violazioni, email usa e getta, corrispondenze tra sessioni e avvisi di rischio. Il report di Verifica email acquisisce l'esito completo di una verifica OTP via email: a chi è stato inviato il messaggio, se l'indirizzo è usa e getta o non recapitabile, se compare in violazioni dei dati note, quanti tentativi ha effettuato l'utente ed eventuali corrispondenze tra sessioni diverse rispetto alla tua blocklist o ad altri utenti approvati. Questa pagina documenta la struttura JSON restituita dall'endpoint di decisione, consentendoti di analizzare gli esiti degli OTP, l'esposizione a violazioni e i flag di rischio per ciascun indirizzo verificato. ![Report di verifica email di Didit che mostra l'esito dell'OTP, i dati sulle violazioni e i flag di rischio](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) ## Panoramica Viene generato un report email ogni volta che un nodo del workflow esegue la funzionalità Verifica email. Ciascun report rappresenta una verifica OTP per un singolo indirizzo e contiene: * L'indirizzo `email` verificato. * Flag di rischio booleani (`is_breached`, `is_disposable`, `is_undeliverable`) e l'array di supporto `breaches[]` proveniente da un database di informazioni sulle violazioni. * Il conteggio dei tentativi di invio dell'OTP (`verification_attempts`) e il timestamp di approvazione. * Un registro cronologico `lifecycle[]` di ogni tentativo di invio, nuovo tentativo e verifica del codice. * Un array `matches[]` che evidenzia lo stesso indirizzo presente in altre verifiche email approvate o nella tua blocklist. * Un array `warnings[]` — eventi di rischio generati durante la verifica (vedi [Avvisi di Verifica email](https://docs.didit.me/it/core-technology/email-verification/warnings-email-verification.md)). * Un `node_id` che identifica quale nodo del grafo del workflow ha prodotto il report (solo sessioni V3). Nelle sessioni di workflow ospitate, la verifica OTP viene eseguita all'interno dell'interfaccia utente di verifica di Didit — ti basta leggere il risultato dal payload di decisione. Per gli OTP da server a server senza un flusso ospitato, utilizza l'API Email autonoma: [`POST /v3/email/send/`](https://docs.didit.me/it/standalone-apis/email-send) invia il codice e [`POST /v3/email/check/`](https://docs.didit.me/it/standalone-apis/email-check) convalida il codice inserito dall'utente; le verifiche autonome completate vengono presentate con la stessa struttura del report. Le sessioni ospitate limitano l'utente a un massimo di **2 inserimenti errati del codice** (`email_max_check_attempts`) e **2 invii di OTP — l'invio iniziale più un reinvio** (`email_max_retries`) per impostazione predefinita, configurabili per nodo del workflow. Il superamento di uno dei due limiti finalizza il passaggio con lo stato `Declined` con `EMAIL_CODE_ATTEMPTS_EXCEEDED`. ## Dove compare nelle risposte API L'endpoint di decisione (`GET /v3/session/{sessionId}/decision/`) restituisce i report email sotto la chiave dell'array in forma plurale **`email_verifications`**. L'array contiene una voce per ogni nodo di Verifica email nel grafo del workflow — in genere una, ma i flussi di step-up possono produrne diverse. ```json theme={null} { "session_id": "11111111-1111-1111-1111-111111111111", "status": "Approved", "email_verifications": [ { "node_id": "feature_email_1", "status": "Approved", "...": "..." } ] } ``` Un valore `null` indica che non è ancora stato eseguito alcun passaggio di Verifica email. Itera sull'array (invece di leggere solo `email_verifications[0]`) se il tuo workflow può raccogliere più di un indirizzo email. ## Schema Lo schema canonico campo per campo è disponibile nella pagina [Modelli di dati](https://docs.didit.me/it/reference/data-models.md#verifica-email). ```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 } ``` Un indirizzo non recapitabile — per sintassi non valida, dominio inesistente, record MX mancanti o mancata consegna dell'OTP — finalizza il passaggio come **`Declined`** con l'avviso di rifiuto automatico `UNDELIVERABLE_EMAIL_DETECTED`. L'unica eccezione: quando l'utente ha digitato personalmente l'indirizzo (non è stato precompilato al momento della creazione della sessione), un invio non recapitabile restituisce un errore inline così da consentirgli di riprovare con un indirizzo diverso anziché essere rifiutato immediatamente. ### Valori di stato | Status | Significato | | - | - | | `Not Finished` | L'invio dell'OTP è stato avviato ma la verifica non è ancora stata finalizzata. | | `Approved` | L'utente ha inserito un OTP valido e non è emerso alcun rischio che comporti il rifiuto. | | `Declined` | È scattato un avviso di rifiuto automatico (blocklist, indirizzo non recapitabile, tentativi superati) o un'azione di rischio configurata su `DECLINE` ha prodotto una corrispondenza. | | `In Review` | Un'azione di rischio configurata su `REVIEW` ha instradato il passaggio verso la revisione manuale. | | `Expired` | La finestra di 5 minuti per l'OTP è trascorsa senza un codice valido — si applica alle verifiche create tramite l'API email standalone. | ### Tipi di eventi del ciclo di vita `lifecycle[]` è ordinato cronologicamente. Ciascun evento include `type`, `timestamp`, `details` e una `fee` fatturabile (se applicabile): | Event type | Emesso quando | | - | - | | `EMAIL_VERIFICATION_MESSAGE_SENT` | Primo tentativo di invio dell'OTP — inclusi gli invii che risultano non recapitabili. | | `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT` | Invio successivo dell'OTP dopo che l'utente ha richiesto un nuovo invio. | | `VALID_CODE_ENTERED` | L'utente ha inviato il codice OTP corretto. | | `INVALID_CODE_ENTERED` | L'utente ha inviato un codice OTP errato o scaduto (viene conteggiato nel limite). | | `EMAIL_VERIFICATION_APPROVED` | Lo stato a livello di funzionalità è stato impostato su `Approved`. | | `EMAIL_VERIFICATION_DECLINED` | Lo stato a livello di funzionalità è stato impostato su `Declined`. | | `EMAIL_VERIFICATION_IN_REVIEW` | Lo stato a livello di funzionalità è stato impostato su `In Review`. | | `EMAIL_VERIFICATION_EXPIRED` | La finestra dell'OTP è trascorsa senza un codice valido (API email standalone). | Il payload di `details` dipende dalla famiglia dell'evento: * **Eventi di invio** (`EMAIL_VERIFICATION_MESSAGE_SENT`, `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`) — `{ status, reason }`. `status` è `Success`, `Retry` o `Undeliverable`; `reason` è `null` a meno che l'invio non sia fallito (`email_can_not_be_delivered`, o `unknown` per valori legacy non riconosciuti). * **Eventi di controllo** (`VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`) — `{ code_tried, status }` con `status` `Approved`, `Failed`, `Expired or Not Found` o `Declined`. * **Eventi di stato finale** — `null`, eccetto `EMAIL_VERIFICATION_DECLINED` / `EMAIL_VERIFICATION_IN_REVIEW`, che contengono `{ "reason": "" }` (ad es. `UNDELIVERABLE_EMAIL_DETECTED`). Gli invii con `status` `Success` o `Undeliverable` registrano la tariffa di Verifica email pari a \$0.02; gli invii `Retry`, gli eventi di controllo e gli eventi di stato riportano sempre `fee: 0`. ### Corrispondenze tra sessioni `matches[]` registra lo stesso indirizzo su verifiche email **precedentemente approvate** nella stessa applicazione — tra sessioni KYC, KYB e API standalone — oltre alle corrispondenze con gli elementi della blocklist configurati nelle [liste della Management API](https://docs.didit.me/it/management-api/lists/overview.md). Le verifiche che condividono il `vendor_data` della sessione corrente sono escluse (lo stesso utente finale non genera corrispondenze con se stesso), l'array è limitato a un massimo di **5** voci, ordinate dalla più datata alla più recente. Quando l'indirizzo è presente nella tua blocklist ma nessuna delle sessioni corrispondenti è inclusa nella blocklist, all'array viene anteposta una voce sintetica con `source: "list_entry"` (tutti i campi della sessione impostati su `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 } ``` ## Esempi ### Approvata — OTP pulito con un avviso informativo ```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:///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": [] } ``` ### Rifiutata — indirizzo non recapitabile Un indirizzo precompilato che non supera la validazione della sintassi o del DNS (MX) — o la cui email con OTP non può essere recapitata — si finalizza immediatamente come `Declined`. Non compare alcun evento di verifica del codice poiché nessun codice ha mai raggiunto l'utente. ```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": [] } ``` ### Rifiutata — casella di posta usa e getta inclusa nella blocklist L'utente ha completato l'OTP, ma l'indirizzo corrispondeva a un elemento della tua blocklist email (rifiuto automatico). Viene segnalato anche il flag che indica un indirizzo email usa e getta — qui a livello `information` poiché `disposable_email_action` è rimasto impostato sul valore predefinito `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" } ] } ``` ## Risorse correlate * [Panoramica di Verifica email](https://docs.didit.me/it/core-technology/email-verification/overview.md) — funzionamento e prezzi della funzionalità. * [Avvisi di Verifica email](https://docs.didit.me/it/core-technology/email-verification/warnings-email-verification.md) — tutti i codici di rischio, trigger di rifiuto e azioni configurabili. * [Modelli di dati — verifica email](https://docs.didit.me/it/reference/data-models.md#verifica-email) — schema canonico campo per campo. * [API Email — Invia OTP](https://docs.didit.me/it/standalone-apis/email-send.md) e [Verifica OTP](https://docs.didit.me/it/standalone-apis/email-check.md) — endpoint server-to-server standalone. * [Management API — Liste](https://docs.didit.me/it/management-api/lists/overview.md) — gestisci la blocklist di email che alimenta `matches[]` con `source: list_entry`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.