> ## 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.

# Informe de verificació de correu: filtracions i OTP

> Interpreta la verificació de correu electrònic de Didit: cicle d'OTP, filtracions, adreces d'un sol ús, lliurament i advertències de risc.

L'informe de Verificació de correu electrònic recull el resultat complet d'un desafiament OTP per correu electrònic: a qui es va enviar el missatge, si l'adreça és d'un sol ús o no lliurable, si apareix en filtracions de dades conegudes, quants intents ha necessitat l'usuari i qualsevol coincidència entre sessions amb la teva llista de bloqueig o altres usuaris aprovats.

Aquesta pàgina documenta l'estructura JSON retornada per l'endpoint de decisió perquè puguis analitzar els resultats de l'OTP, l'exposició a filtracions i els indicadors de risc de cada adreça verificada.

![Informe de verificació de correu electrònic de Didit que mostra el resultat de l'OTP, les dades de filtracions i els indicadors de risc](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)

## Visió general

Es genera un informe de correu electrònic cada vegada que un node del flux de treball executa la funcionalitat de Verificació de correu electrònic. Cada informe representa un desafiament OTP per a una adreça i conté:

* L'adreça `email` verificada.
* Indicadors de risc booleans (`is_breached`, `is_disposable`, `is_undeliverable`) i l'array complementari `breaches[]` procedent d'una base de dades d'intel·ligència de filtracions.
* El recompte d'intents d'enviament de l'OTP (`verification_attempts`) i la marca de temps d'aprovació.
* Un registre cronològic `lifecycle[]` de cada intent d'enviament, reintent i comprovació de codi.
* Un array `matches[]` que mostra la mateixa adreça en altres verificacions de correu electrònic aprovades o a la teva llista de bloqueig.
* Un array `warnings[]`: esdeveniments de risc emesos durant la verificació (consulta [Advertències de Verificació de correu electrònic](https://docs.didit.me/ca/core-technology/email-verification/warnings-email-verification.md)).
* Un `node_id` que identifica quin node del graf del flux de treball ha generat l'informe (només en sessions V3).

En sessions de flux de treball allotjades, el desafiament OTP s'executa dins de la IU de verificació de Didit; només cal que llegeixis el resultat del payload de decisió. Per a un OTP de servidor a servidor sense un flux allotjat, utilitza l'API independent de correu electrònic: [`POST /v3/email/send/`](https://docs.didit.me/ca/standalone-apis/email-send) lliura el codi i [`POST /v3/email/check/`](https://docs.didit.me/ca/standalone-apis/email-check) valida l'entrada de l'usuari; les verificacions independents finalitzades es mostren mitjançant la mateixa estructura d'informe.

Per defecte, les sessions allotjades limiten l'usuari a **2 entrades de codi incorrectes** (`email_max_check_attempts`) i **2 enviaments d'OTP: l'enviament inicial més un reenviament** (`email_max_retries`), configurable per cada node del flux de treball. Si se supera qualsevol dels dos límits, el pas finalitza com a `Declined` amb `EMAIL_CODE_ATTEMPTS_EXCEEDED`.

## On apareix a les respostes de l'API

L'endpoint de decisió (`GET /v3/session/{sessionId}/decision/`) retorna informes de correu electrònic sota la clau d'array en plural **`email_verifications`**. L'array conté una entrada per cada node de Verificació de correu electrònic al graf del flux de treball; normalment una, però els fluxos amb verificació addicional (step-up) en poden generar diverses.

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

Un valor `null` significa que encara no s'ha executat cap pas de Verificació de correu electrònic. Itera l'array (en lloc de llegir `email_verifications[0]`) quan el teu flux de treball pugui recopilar més d'una adreça de correu electrònic.

## Esquema

L'esquema canònic camp per camp es troba a la pàgina [Models de dades](https://docs.didit.me/ca/reference/data-models.md#verificació-de-correu-electrònic).

```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
}
```

Una adreça no lliurable (sintaxi no vàlida, un domini inexistent, registres MX absents o un lliurament d'OTP fallit) finalitza el pas com a **`Declined`** amb l'advertència de rebuig automàtic `UNDELIVERABLE_EMAIL_DETECTED`. L'única excepció: quan l'usuari ha escrit l'adreça ell mateix (no s'ha emplenat prèviament en crear la sessió), un enviament no lliurable retorna un error en línia per tal que pugui reintentar-ho amb una adreça diferent en lloc de ser rebutjat immediatament.

### Valors d'estat

| Estat | Significat |
| - | - |
| `Not Finished` | S'ha iniciat l'enviament de l'OTP, però la verificació encara no s'ha finalitzat. |
| `Approved` | L'usuari ha introduït un OTP vàlid i no s'ha detectat cap risc que en provoqui el rebuig. |
| `Declined` | S'ha activat una advertència de rebuig automàtic (llista de bloqueig, adreça no lliurable, intents superats) o s'ha complert una acció de risc configurada a `DECLINE`. |
| `In Review` | Una acció de risc configurada a `REVIEW` ha derivat el pas a revisió manual. |
| `Expired` | S'ha esgotat la finestra de 5 minuts per a l'OTP sense cap codi vàlid; s'aplica a les verificacions creades mitjançant l'API de correu electrònic independent. |

### Tipus d'esdeveniments del cicle de vida

`lifecycle[]` està ordenat cronològicament. Cada esdeveniment té `type`, `timestamp`, `details` i una `fee` facturable (quan correspongui):

| Tipus d'esdeveniment | S'emet quan |
| - | - |
| `EMAIL_VERIFICATION_MESSAGE_SENT` | Primer intent d'enviament de l'OTP, inclosos els enviaments que retornen com a no lliurables. |
| `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT` | Enviament posterior de l'OTP després que l'usuari hagi sol·licitat un reenviament. |
| `VALID_CODE_ENTERED` | L'usuari ha enviat el codi OTP correcte. |
| `INVALID_CODE_ENTERED` | L'usuari ha enviat un codi OTP incorrecte o caducat (compta per al límit màxim). |
| `EMAIL_VERIFICATION_APPROVED` | L'estat de la funcionalitat s'ha establert a `Approved`. |
| `EMAIL_VERIFICATION_DECLINED` | L'estat de la funcionalitat s'ha establert a `Declined`. |
| `EMAIL_VERIFICATION_IN_REVIEW` | L'estat de la funcionalitat s'ha establert a `In Review`. |
| `EMAIL_VERIFICATION_EXPIRED` | S'ha esgotat la finestra de l'OTP sense un codi vàlid (API de correu electrònic independent). |

El payload de `details` depèn de la família d'esdeveniments:

* **Esdeveniments d'enviament** (`EMAIL_VERIFICATION_MESSAGE_SENT`, `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`) — `{ status, reason }`. `status` és `Success`, `Retry` o `Undeliverable`; `reason` és `null` tret que l'enviament hagi fallat (`email_can_not_be_delivered`, o `unknown` per a valors heretats no reconeguts).
* **Esdeveniments de comprovació** (`VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`) — `{ code_tried, status }` amb `status` `Approved`, `Failed`, `Expired or Not Found` o `Declined`.
* **Esdeveniments d'estat final** — `null`, excepte `EMAIL_VERIFICATION_DECLINED` / `EMAIL_VERIFICATION_IN_REVIEW`, que contenen `{ "reason": "<risk code>" }` (per exemple, `UNDELIVERABLE_EMAIL_DETECTED`).

Els enviaments amb `status` `Success` o `Undeliverable` registren la tarifa de Verificació de correu electrònic de \$0.02; els enviaments `Retry`, els esdeveniments de comprovació i els esdeveniments d'estat sempre porten `fee: 0`.

### Coincidències entre sessions

`matches[]` registra la mateixa adreça en verificacions de correu electrònic **aprovades prèviament** a la mateixa aplicació —entre sessions de KYC, KYB i de l'API independent—, a més de coincidències amb la llista de bloqueig configurada a les [llistes de l'API de gestió](https://docs.didit.me/ca/management-api/lists/overview.md). S'exclouen les verificacions que comparteixen el `vendor_data` de la sessió actual (el mateix usuari final no coincideix amb si mateix), la matriu està limitada a **5** entrades, ordenades de més antiga a més recent. Quan l'adreça és a la teva llista de bloqueig però cap de les sessions coincidents està a la llista de bloqueig, s'anteposa a la matriu una entrada sintètica amb `source: "list_entry"` (tots els camps de la sessió a `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
}
```

## Exemples

### Aprovada — OTP net amb una alerta informativa

```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": []
}
```

### Rebutjada — adreça no lliurable

Una adreça emplenada prèviament que no supera la validació de sintaxi o DNS (MX) —o el correu electrònic amb l'OTP de la qual no es pot lliurar— finalitza immediatament com a `Declined`. No apareix cap esdeveniment de comprovació de codi perquè no va arribar mai cap codi a l'usuari.

```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": []
}
```

### Rebutjada — bústia d'un sol ús a la llista de bloqueig

L'usuari ha completat l'OTP, però l'adreça ha coincidit amb la teva llista de bloqueig de correu electrònic (rebuig automàtic). L'indicador de bústia d'un sol ús també s'activa —aquí, amb nivell `information`, perquè `disposable_email_action` manté el seu valor predeterminat `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"
    }
  ]
}
```

## Relacionat

* [Visió general de la Verificació de correu electrònic](https://docs.didit.me/ca/core-technology/email-verification/overview.md) — comportament de la funcionalitat i preus.
* [Advertències de la Verificació de correu electrònic](https://docs.didit.me/ca/core-technology/email-verification/warnings-email-verification.md) — tots els codis de risc, activadors de rebuig i accions configurables.
* [Models de dades — verificació de correu electrònic](https://docs.didit.me/ca/reference/data-models.md#verificació-de-correu-electrònic) — esquema canònic camp per camp.
* [API de correu electrònic — Enviar OTP](https://docs.didit.me/ca/standalone-apis/email-send.md) i [Comprovar OTP](https://docs.didit.me/ca/standalone-apis/email-check.md) — endpoints independents de servidor a servidor.
* [Management API — Llistes](https://docs.didit.me/ca/management-api/lists/overview.md) — gestiona la llista de bloqueig de correu electrònic que alimenta `matches[]` amb `source: list_entry`.


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