Verifica email: avvisi e codici di rischio

La funzionalità di Verifica email emette avvisi ogni volta che si attiva un segnale di rischio sul flusso OTP o sull’indirizzo stesso: una violazione dei dati nota, un provider usa e getta, una casella di posta non recapitabile, il superamento del limite di tentativi OTP, oppure una corrispondenza con la tua blocklist o con un’altra verifica approvata. Questa pagina elenca ciascun codice, cosa lo attiva e come configurare la risposta del workflow.

Panoramica

Gli avvisi sono contrassegnati con la funzionalità EMAIL. Compaiono nel report sotto email_verifications[].warnings[] e seguono la struttura standard dell’oggetto avviso (feature, risk, additional_data, log_type, short_description, long_description, node_id). Ciascun avviso viene inoltre instradato nel registro per sessione in modo da apparire nella Business Console nella sezione Email. Alcuni avvisi sono trigger di rifiuto automatico vincolante: impostano sempre lo stato della funzionalità su Declined e presentano log_type: "error". Gli altri corrispondono a un’azione configurabile (DECLINE, REVIEW o il valore predefinito NO_ACTION) definita per nodo del workflow o per chiamata API, quindi lo stesso codice di rischio può rifiutare un workflow e limitarsi a segnalarne un altro. L’azione configurata definisce anche la gravità: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Condizioni di rifiuto automatico

I seguenti avvisi rifiutano sempre il passaggio di Verifica email, indipendentemente dalla configurazione:

EMAIL_CODE_ATTEMPTS_EXCEEDED — l’utente ha esaurito il budget di OTP: per impostazione predefinita, 2 inserimenti di codice errati (email_max_check_attempts) o 2 invii di OTP — l’invio iniziale più un nuovo invio (email_max_retries).
EMAIL_IN_BLOCKLIST — l’indirizzo è presente in una blocklist gestita tramite la Lists API, oppure ha trovato corrispondenza con una verifica email precedentemente approvata che è stata inserita nella blocklist.
UNDELIVERABLE_EMAIL_DETECTED — l’indirizzo non può ricevere email: sintassi non valida, dominio inesistente, record DNS (MX) mancanti o impossibilità di recapitare l’email OTP. Il passaggio si conclude immediatamente come Declined — non viene mai eseguito alcun controllo del codice. Eccezione: quando l’utente ha digitato l’indirizzo autonomamente (non era precompilato al momento della creazione della sessione), un invio non recapitabile restituisce un errore contestuale che consente di riprovare con un indirizzo diverso, anziché rifiutare il passaggio.

Rischi configurabili

Ciascuno dei seguenti rischi corrisponde a un’impostazione (per nodo del workflow, o per chiamata sull’endpoint di controllo autonomo) che puoi configurare su DECLINE, REVIEW o NO_ACTION:

Impostazione	Codice di rischio	Comportamento predefinito
`breached_email_action`	`BREACHED_EMAIL_DETECTED`	`NO_ACTION` — mostra i dettagli della violazione a livello `information` senza modificare lo stato.
`disposable_email_action`	`DISPOSABLE_EMAIL_DETECTED`	`NO_ACTION` — segnala il provider usa e getta a livello `information` senza modificare lo stato.
`duplicated_email_action`	`DUPLICATED_EMAIL`	`NO_ACTION` — registra il duplicato a livello `information`. Viene ignorato se l’indirizzo è nella lista consentita.

Il rilevamento dei duplicati prende in considerazione solo le verifiche email precedentemente approvate nella stessa applicazione, raggruppate per vendor_data — le verifiche che condividono lo stesso vendor_data vengono considerate come un unico utente finale ed escluse. Se lasci vendor_data vuoto, ogni sessione viene trattata come un utente distinto. Se l’indirizzo è presente nella tua lista consentita di indirizzi email, l’azione sul duplicato viene ignorata e viene invece emesso EMAIL_IN_ALLOWLIST.

Limiti dei tentativi di verifica

La funzionalità di Verifica email applica un limite rigido ai tentativi di OTP per prevenire abusi:

Tentativi di inserimento del codice — email_max_check_attempts, valore predefinito 2: il secondo codice errato (o scaduto) conclude il passaggio.
Tentativi di invio — email_max_retries, valore predefinito 2 invii in totale (l’invio iniziale più un nuovo invio): un’ulteriore richiesta di nuovo invio conclude il passaggio.

Il superamento di uno dei due limiti genera EMAIL_CODE_ATTEMPTS_EXCEEDED e comporta il rifiuto automatico. Puoi regolare entrambi i limiti per ciascun nodo del workflow.

Avvisi generati

Tag	Gravità	Descrizione
`EMAIL_CODE_ATTEMPTS_EXCEEDED`	`error`	L’utente ha superato il limite di invii o di tentativi di inserimento del codice. Rifiutata automaticamente.
`EMAIL_IN_BLOCKLIST`	`error`	L’indirizzo è presente in una blocklist creata tramite la Lists API, oppure corrisponde a una verifica approvata presente in blocklist. Rifiutata automaticamente. `additional_data` contiene `blocklisted_session_id`, `blocklisted_session_number` e `api_service` (tutti `null` per una corrispondenza diretta con la lista).
`EMAIL_IN_ALLOWLIST`	`information`	L’indirizzo corrisponde a una allowlist creata tramite la Lists API, pertanto l’azione per email duplicata è stata ignorata.
`BREACHED_EMAIL_DETECTED`	In base a `breached_email_action` (`information` per impostazione predefinita)	L’indirizzo è stato trovato in una o più violazioni di dati note. L’array `breaches[]` nel report riporta il servizio violato, la data e le classi di dati.
`DISPOSABLE_EMAIL_DETECTED`	In base a `disposable_email_action` (`information` per impostazione predefinita)	Il dominio appartiene a un provider di email usa e getta / temporanee noto, spesso utilizzato per eludere la tracciabilità.
`UNDELIVERABLE_EMAIL_DETECTED`	`error`	L’indirizzo non può ricevere messaggi (sintassi non valida, dominio inesistente, record MX mancanti o mancata consegna). Rifiutata automaticamente.
`DUPLICATED_EMAIL`	In base a `duplicated_email_action` (`information` per impostazione predefinita)	L’indirizzo corrisponde a una verifica email precedentemente approvata appartenente a un utente finale diverso (raggruppato per `vendor_data`). `additional_data` contiene `duplicated_session_id`, `duplicated_session_number` e `api_service`.

Viene attivato al massimo uno tra EMAIL_IN_BLOCKLIST, DUPLICATED_EMAIL e EMAIL_IN_ALLOWLIST per tentativo: la blocklist ha la precedenza sui duplicati, che a loro volta hanno la precedenza sull’allowlist.

Corrispondenze tra sessioni

Quando un indirizzo viene rilevato in verifiche email precedentemente approvate o nella tua blocklist, tali riscontri compaiono anche in email_verifications[].matches[] (fino a un massimo di 5 voci). Ciascuna corrispondenza include session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service e un valore di source pari a session (un’altra verifica approvata) o list_entry (una voce della blocklist). Se l’indirizzo attuale si trova nella tua allowlist delle email, Didit conserva le evidenze della corrispondenza ma genera EMAIL_IN_ALLOWLIST invece di applicare l’azione per email duplicata. Consulta il report di Verifica email per lo schema completo delle corrispondenze.

Esempio

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

Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I livelli di gravità si dividono in tre categorie:

Correlati

Panoramica di Verifica email — comportamento della funzionalità e prezzi.
Report di Verifica email — struttura completa della risposta, inclusi lifecycle[] e matches[].
Modelli di dati — verifica email — schema canonico campo per campo.
API di gestione — Lists — gestione della blocklist email utilizzata da EMAIL_IN_BLOCKLIST.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Verifica email: avvisi e codici di rischio

Panoramica

Condizioni di rifiuto automatico

Rischi configurabili

Limiti dei tentativi di verifica

Avvisi generati

Corrispondenze tra sessioni

Esempio

Tipi di avviso

Correlati

​Panoramica

​Condizioni di rifiuto automatico

​Rischi configurabili

​Limiti dei tentativi di verifica

​Avvisi generati

​Corrispondenze tra sessioni

​Esempio

​Tipi di avviso

​Correlati

Panoramica

Condizioni di rifiuto automatico

Rischi configurabili

Limiti dei tentativi di verifica

Avvisi generati

Corrispondenze tra sessioni

Esempio

Tipi di avviso

Correlati