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

# Avisos e códigos de risco da Verificação de e-mail

> Guia de códigos de risco da Verificação de e-mail na Didit: e-mails violados, descartáveis, não entregáveis, lista de bloqueio e limites de OTP.

A funcionalidade Verificação de e-mail emite **avisos** sempre que um sinal de risco é acionado no fluxo de OTP ou no próprio endereço: uma violação de dados conhecida, um fornecedor descartável, uma caixa de correio que não pode receber mensagens, um limite de tentativas de OTP ou uma correspondência com a sua lista de bloqueio ou outra verificação aprovada. Esta página lista cada código, o que o desencadeia e como configurar a resposta do fluxo.

## Visão geral

Os avisos são identificados com a funcionalidade `EMAIL`. Surgem no relatório em `email_verifications[].warnings[]` e seguem o formato padrão do [objeto de aviso](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Cada aviso é também encaminhado para o registo por sessão, de modo a surgir na Business Console na secção Email.

Alguns avisos são acionadores de **recusa automática estrita** — definem sempre o estado da funcionalidade como `Declined` e contêm `log_type: "error"`. Os restantes correspondem a uma **ação configurável** (`DECLINE`, `REVIEW` ou a predefinida `NO_ACTION`) definida por nó do fluxo ou por chamada de API, pelo que o mesmo código de risco pode recusar um fluxo enquanto apenas sinaliza outro. A ação configurada também define a gravidade: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

## Condições de recusa automática

Os seguintes avisos recusam sempre o passo de Verificação de e-mail, independentemente da configuração:

* `EMAIL_CODE_ATTEMPTS_EXCEEDED` — o utilizador esgotou o limite de OTP: 2 introduções incorretas de código (`email_max_check_attempts`) ou 2 envios de OTP — o envio inicial mais um reenvio (`email_max_retries`) — por predefinição.
* `EMAIL_IN_BLOCKLIST` — o endereço está numa lista de bloqueio gerida através da [Lists API](https://docs.didit.me/pt/management-api/lists/overview.md), ou correspondeu a uma verificação de e-mail previamente aprovada que foi colocada na lista de bloqueio.
* `UNDELIVERABLE_EMAIL_DETECTED` — o endereço não pode receber mensagens: sintaxe inválida, um domínio inexistente, registos DNS (MX) em falta ou impossibilidade de entrega do e-mail com o OTP. O passo é concluído imediatamente como `Declined` — nenhuma verificação de código chega a ser executada. Exceção: quando o próprio utilizador introduziu o endereço (não foi pré-preenchido na criação da sessão), um envio não entregável devolve um erro apresentado em linha para que possa tentar novamente com um endereço diferente em vez de ser recusado.

## Riscos configuráveis

Cada um dos seguintes riscos corresponde a uma definição (por nó do fluxo ou por chamada no [endpoint de verificação](https://docs.didit.me/pt/standalone-apis/email-check.md) autónomo) que pode configurar como `DECLINE`, `REVIEW` ou `NO_ACTION`:

| Definição | Código de risco | Comportamento predefinido |
| - | - | - |
| `breached_email_action` | `BREACHED_EMAIL_DETECTED` | `NO_ACTION` — apresenta os detalhes da violação com o nível `information` sem alterar o estado. |
| `disposable_email_action` | `DISPOSABLE_EMAIL_DETECTED` | `NO_ACTION` — sinaliza o fornecedor descartável com o nível `information` sem alterar o estado. |
| `duplicated_email_action` | `DUPLICATED_EMAIL` | `NO_ACTION` — regista o duplicado com o nível `information`. Ignorado quando o endereço está na lista de permissões. |

A deteção de duplicados apenas considera verificações de e-mail **previamente aprovadas** na mesma aplicação, agrupadas por `vendor_data` — as verificações que partilham o mesmo `vendor_data` são tratadas como um único utilizador final e excluídas. Se deixar `vendor_data` vazio, cada sessão é tratada como um utilizador distinto. Se o endereço estiver na sua lista de permissões de e-mail, a ação de duplicado é ignorada e é emitido `EMAIL_IN_ALLOWLIST` em alternativa.

## Limites de tentativas de verificação

A funcionalidade Verificação de e-mail aplica um limite estrito nas tentativas de OTP para prevenir abusos:

* **Tentativas de introdução de código** — `email_max_check_attempts`, predefinição **2**: o segundo código incorreto (ou expirado) conclui o passo.
* **Tentativas de envio** — `email_max_retries`, predefinição **2** envios no total (o envio inicial mais um reenvio): um pedido de reenvio adicional conclui o passo.

Ultrapassar qualquer um dos limites aciona `EMAIL_CODE_ATTEMPTS_EXCEEDED` e recusa automaticamente. Pode ajustar ambos os limites por nó do fluxo.

## Avisos gerados

| Tag | Severidade | Descrição |
| - | - | - |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | `error` | O utilizador excedeu o limite de introdução de código ou de envio. Recusa automática. |
| `EMAIL_IN_BLOCKLIST` | `error` | O endereço está presente numa lista de bloqueio criada através da [Lists API](https://docs.didit.me/pt/management-api/lists/overview.md), ou correspondeu a uma verificação aprovada que consta da lista de bloqueio. Recusa automática. `additional_data` contém `blocklisted_session_id`, `blocklisted_session_number` e `api_service` (todos `null` no caso de uma correspondência exclusiva de lista). |
| `EMAIL_IN_ALLOWLIST` | `information` | O endereço coincidiu com uma lista de permissões criada através da [Lists API](https://docs.didit.me/pt/management-api/lists/overview.md), pelo que a ação de e-mail duplicado foi ignorada. |
| `BREACHED_EMAIL_DETECTED` | Conforme `breached_email_action` (`information` por predefinição) | O endereço foi encontrado numa ou mais violações de dados conhecidas. O array `breaches[]` no relatório contém o serviço afetado pela violação de dados, a data e as categorias de dados. |
| `DISPOSABLE_EMAIL_DETECTED` | Conforme `disposable_email_action` (`information` por predefinição) | O domínio é um fornecedor de e-mails descartáveis / temporários conhecido, frequentemente utilizado para evitar a rastreabilidade. |
| `UNDELIVERABLE_EMAIL_DETECTED` | `error` | O endereço não consegue receber mensagens (sintaxe inválida, domínio inexistente, registos MX em falta ou falha na entrega). Recusa automática. |
| `DUPLICATED_EMAIL` | Conforme `duplicated_email_action` (`information` por predefinição) | O endereço coincide com uma verificação de e-mail previamente aprovada pertencente a um utilizador final diferente (agrupado por `vendor_data`). `additional_data` contém `duplicated_session_id`, `duplicated_session_number` e `api_service`. |

No máximo, um de `EMAIL_IN_BLOCKLIST`, `DUPLICATED_EMAIL` e `EMAIL_IN_ALLOWLIST` é acionado por tentativa — a lista de bloqueio tem precedência sobre a correspondência duplicada, que tem precedência sobre a lista de permissões.

## Correspondências entre sessões

Quando um endereço é detetado em verificações de e-mail previamente aprovadas ou na sua lista de bloqueio, essas ocorrências também aparecem em `email_verifications[].matches[]` (limitado a 5 entradas). Cada correspondência contém `session_id`, `session_number`, `vendor_data`, `verification_date`, `email`, `status`, `is_blocklisted`, `api_service` e uma `source` de `session` (outra verificação aprovada) ou `list_entry` (uma entrada da lista de bloqueio). Se o endereço atual estiver na sua lista de permissões de e-mail, a Didit mantém a evidência da correspondência, mas emite `EMAIL_IN_ALLOWLIST` em vez de aplicar a ação de e-mail duplicado. Consulte o [relatório de Verificação de e-mail](https://docs.didit.me/pt/core-technology/email-verification/report-email-verification.md#correspondências-entre-sessões) para obter o esquema completo de correspondência.

## Exemplo

```json theme={null}
{
  "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"
    }
  ]
}
```

## Tipos de aviso

A cada risco é atribuída uma severidade com base na configuração da sua aplicação. As severidades dividem-se em três categorias:

## Relacionado

* [Visão geral da Verificação de e-mail](https://docs.didit.me/pt/core-technology/email-verification/overview.md) — comportamento da funcionalidade e preços.
* [Relatório de Verificação de e-mail](https://docs.didit.me/pt/core-technology/email-verification/report-email-verification.md) — formato completo da resposta, incluindo `lifecycle[]` e `matches[]`.
* [Modelos de dados — verificação de e-mail](https://docs.didit.me/pt/reference/data-models.md#verificação-de-e-mail) — esquema canónico campo a campo.
* [Management API — Listas](https://docs.didit.me/pt/management-api/lists/overview.md) — faça a gestão da lista de bloqueio de e-mail utilizada por `EMAIL_IN_BLOCKLIST`.


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