# Veredictos y reason codes

Toda verificación responde con un `verdict` y un `reason_code`. El veredicto es la decisión; el reason code es la evidencia que la sostiene.

## Los cuatro veredictos

| `verdict` | Significado | Qué hacer |
| --- | --- | --- |
| `valid` | El servidor de correo acepta al destinatario y rechaza una dirección de control aleatoria en el mismo servidor | Envía. No demuestra que alguien lea el buzón |
| `invalid` | Sintaxis no admitida, un dominio que no puede recibir correo o un «no existe ese destinatario» inequívoco | No envíes. Elimínala o pide una corrección |
| `risky` | Servidor que lo acepta todo, dominio desechable o heredado, reenvío, buzón lleno o desactivado, o un rechazo del proveedor sin confirmar | Decide según `reason_code` y según lo que te cueste un rebote |
| `unknown` | Buzón no comprobado (`basic`), tiempo agotado, greylisting, fallo temporal de DNS o SMTP, cuota de sondeo o respuesta ambigua | Consérvala. Reintenta después de `retry_at` cuando venga informado |

**Nunca trates `unknown` como `invalid`.** `unknown` significa «no hemos podido saberlo», no «no existe». En modo `mailbox`, un resultado `unknown` nunca se cobra.

Solo el modo `mailbox` puede devolver `valid`. El modo `basic` nunca contacta con el servidor de correo, así que un dominio sano da `unknown` con `mailbox_not_checked`.

## Reason codes

«Modo» indica dónde puede aparecer el código. Pueden añadirse códigos nuevos sin cambiar de versión: cuando encuentres uno que no conozcas, guíate por el `verdict`.

### `valid`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `mailbox_exists` | mailbox | Destinatario aceptado y dirección de control aleatoria rechazada | Envía |

### `invalid`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `syntax_invalid` | ambos | No es una dirección válida en el perfil ASCII admitido | Pide una corrección. No envíes nunca |
| `domain_not_found` | ambos | El dominio no existe (NXDOMAIN) | Suele ser una errata en el dominio. Pide una corrección |
| `domain_null_mx` | ambos | El dominio declara que no acepta correo (MX nulo, RFC 7505) | Elimínala |
| `domain_no_mail_host` | ambos | Sin registro MX y sin registro A ni AAAA | Elimínala |
| `mailbox_not_found` | mailbox | El servidor dice que el destinatario no existe | Elimínala. Un envío rebotaría |

### `risky`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `disposable_domain` | ambos | El dominio está en la lista de emails desechables | Recházala en el registro o exclúyela de las campañas, según tu política |
| `legacy_domain` | ambos | Dominio de un proveedor que ya no existe | Pide una dirección actual. No cuentes con ella |
| `mailbox_disabled` | mailbox | El servidor dice que el buzón está desactivado | No envíes. Vuelve a comprobarla más adelante si el contacto importa |
| `mailbox_full` | mailbox | El servidor dice que el buzón está lleno | Un envío probablemente rebotaría. Vuelve a comprobarla más adelante |
| `mailbox_forwarded` | mailbox | El servidor anuncia un reenvío (SMTP 251) | Suele entregarse. El buzón final no se verifica |
| `provider_directory_rejected` | mailbox | Rechazo del directorio del proveedor (Microsoft 365) sin confirmar | Trátala como probablemente inexistente. Déjala fuera de los envíos masivos |
| `catch_all` | mailbox | El servidor también acepta a un destinatario aleatorio | El buzón no se puede confirmar. Envía solo si tienes otra señal, como actividad reciente |

### `unknown`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `mailbox_not_checked` | basic | El dominio puede recibir correo y el buzón no se sondeó | Respuesta normal en `basic`. Usa el modo `mailbox` si necesitas certeza |
| `address_unsupported` | ambos | Dirección internacionalizada (no ASCII), no comprobada | No la rechaces. Verifícala por tus propios medios |
| `dns_temporary` | ambos | El DNS falló temporalmente. No se cobra | Reintenta más tarde |
| `catch_all_unresolved` | mailbox | Destinatario aceptado, pero el control de catch-all no fue concluyente | Reintenta más tarde. Hasta entonces, trátala como `catch_all` |
| `rejection_unconfirmed` | mailbox | Rechazada, pero una dirección de control que sabemos buena también lo fue | El rechazo no demuestra nada. Reintenta más tarde |
| `probe_rate_limited` | mailbox | Nuestra cuota horaria de sondeo para ese dominio o servidor está agotada | Reintenta después de `retry_at`. Los lotes lo hacen por ti |
| `probe_blocked` | mailbox | El servidor rechaza nuestro sondeo (reputación de IP, DNS inverso o política del remitente) | Reintentar no servirá a corto plazo. Trátala como no verificada |
| `smtp_temporary` | mailbox | Rechazo temporal o greylisting | Reintenta después de `retry_at`. Los lotes lo hacen por ti |
| `smtp_unreachable` | mailbox | No se pudo contactar con ningún servidor de correo | Reintenta más tarde |
| `smtp_tls_failed` | mailbox | No se pudo verificar la sesión TLS anunciada | Reintenta más tarde |
| `smtp_rejected` | mailbox | Rechazo ambiguo o por política que no demuestra que el buzón falte | Trátala como no verificada |

## El resto del resultado

```json
{
  "id": "ver_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "verification",
  "livemode": true,
  "email": "luis@example.org",
  "mode": "mailbox",
  "verdict": "unknown",
  "reason_code": "smtp_temporary",
  "reason": "The mail server deferred the check; try again after retry_at.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    },
    {
      "name": "smtp",
      "status": "temporary"
    }
  ],
  "mx": [
    {
      "host": "mail.example.org",
      "preference": 5
    }
  ],
  "smtp": {
    "mx": "mail.example.org",
    "code": 451,
    "enhanced_code": "4.7.1",
    "tls": true
  },
  "cached": false,
  "credits_charged": 0,
  "checked_at": "2026-11-17T09:51:10Z",
  "retry_at": "2026-11-17T10:06:10Z"
}
```

| Campo | Qué te dice |
| --- | --- |
| `reason` | Explicación legible de `reason_code`, en inglés o español (`Accept-Language`) |
| `flags.disposable` | El dominio, o un dominio padre, está en la lista de desechables |
| `flags.free` | Proveedor de correo gratuito. Informativo: no cambia el veredicto |
| `flags.catch_all` | `true`: el servidor aceptó a un destinatario aleatorio. `false`: lo rechazó. `null`: no se probó o no fue concluyente |
| `checks` | Los pasos que se ejecutaron de verdad, en orden: `syntax`, listas de dominios, `dns`, `smtp`, `catch_all`. Los que no se ejecutaron no aparecen |
| `mx` | Servidores de correo del dominio. Vacío cuando no se resolvió el DNS |
| `smtp` | Lo que respondió el servidor a `RCPT TO`: `mx`, `code`, `enhanced_code`, `tls`. `null` en modo `basic` |
| `cached` | El resultado viene de una comprobación reciente. `checked_at` es la hora de esa comprobación |
| `credits_charged` | `0` o `1` crédito del tipo de `mode` |
| `retry_at` | Cuándo se puede volver a verificar un resultado temporal. `null` cuando reintentar no tiene sentido |

## Una política razonable de partida

| Situación | Enviar a `valid` | Enviar a `risky` | Enviar a `unknown` |
| --- | --- | --- | --- |
| Email transaccional que el usuario ha pedido | Sí | Sí | Sí |
| Boletín a personas que se suscribieron | Sí | Solo `mailbox_forwarded` y `catch_all` con actividad reciente | Tras un reintento, o en tandas pequeñas vigilando los rebotes |
| Lista fría o antigua | Sí | No | No, hasta que un reintento dé un veredicto |

Es un punto de partida, no una norma: tú sabes lo que te cuesta un rebote.
