# Verificación en el registro

Frena erratas, dominios muertos y direcciones desechables en el formulario, sin hacer esperar a los usuarios reales.

## El patrón recomendado

1. El formulario envía los datos a **tu servidor**. La clave de API nunca llega al navegador.
2. Tu servidor llama a `POST /verify` con `"mode": "basic"` y un tiempo de espera corto.
3. Rechaza los `invalid`, aplica tu política a los dominios desechables y acepta el resto.
4. Si la llamada falla o se agota el tiempo, **acepta el registro** y verifica después.
5. Envía tu email de confirmación como siempre.

**JavaScript / TypeScript**

```js
// Decides what to do with the address typed in a sign-up form. Run it on your server.
async function checkSignupEmail(email) {
  let response;
  try {
    response = await fetch("https://api.salchimail.com/v1/verify", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email, mode: "basic" }),
      signal: AbortSignal.timeout(3000), // never keep the form waiting
    });
  } catch {
    return "accept"; // timeout or network error: fail open and verify later
  }
  if (!response.ok) {
    // 429, 402 or 5xx must not cost you a sign-up. A 400 or 401 is a bug on your side: log it.
    console.error("SalchiMail answered", response.status, response.headers.get("X-Request-Id"));
    return "accept";
  }

  const { verdict, reason_code } = await response.json();
  if (verdict === "invalid") return "reject"; // bad syntax or a domain that cannot receive mail
  if (reason_code === "disposable_domain") return "reject"; // your policy: could also be "review"
  return "accept"; // "unknown" is the normal basic answer: the domain can receive mail
}

console.log(await checkSignupEmail("ana@example.com"));
```

## Tiempos

| Modo | Respuesta habitual | Tiempo de espera recomendado | Dónde ejecutarlo |
| --- | --- | --- | --- |
| `basic` | Bastante menos de un segundo | 3 segundos | En línea, mientras se envía el formulario |
| `mailbox` | Hasta 30 segundos | Más de 30 segundos | En una tarea en segundo plano, después del registro |

`basic` nunca contacta con el servidor de correo, por eso es rápido. `mailbox` habla con el servidor del destinatario: si no termina en 30 segundos, la API responde `503 verification_timeout` y no cobra nada. No dejes un formulario de registro esperando a una comprobación de buzón.

Si quieres la certeza del buzón para los usuarios nuevos, lanza una verificación `mailbox` desde una tarea en segundo plano cuando la cuenta ya exista y actúa según el resultado antes de tu primera campaña.

## Qué hacer con cada resultado

| Resultado en modo `basic` | Significado | Acción recomendada |
| --- | --- | --- |
| `invalid` · `syntax_invalid` | No es una dirección de email | Pide al usuario que la corrija |
| `invalid` · `domain_not_found`, `domain_null_mx`, `domain_no_mail_host` | El dominio no puede recibir correo. Suele ser una errata | Pide al usuario que revise el dominio |
| `risky` · `disposable_domain` | Dirección de usar y tirar | Recházala o pide otra dirección, según tu política |
| `risky` · `legacy_domain` | Dominio de un proveedor que ya no existe | Pide otra dirección |
| `unknown` · `mailbox_not_checked` | El dominio puede recibir correo. Es la respuesta normal | Acepta |
| `unknown` · `dns_temporary`, `address_unsupported` | La comprobación no se pudo hacer | Acepta |

`flags.free` te dice que el dominio es de un proveedor de correo gratuito. Es informativo y no cambia el veredicto.

Para mostrar un mensaje al usuario, asocia cada `reason_code` a tu propio texto. `reason` es una explicación ya redactada en inglés o, con la cabecera `Accept-Language: es`, en español.

## Reglas para no perder registros

- **Ante un fallo, deja pasar.** Un tiempo de espera agotado, un `429`, un `402` o un `5xx` nunca deben costarte un usuario real. Acepta y verifica después.
- **Nunca trates `unknown` como `invalid`.** En modo `basic`, `unknown` es la respuesta para cualquier dominio sano.
- **Mantén tu email de confirmación.** `valid` dice que el servidor acepta la dirección. No demuestra que la persona sea su dueña ni que la lea.
- **Los reenvíos del formulario salen baratos.** Verificar otra vez la misma dirección en 30 días en modo `basic` es gratis: a quien envía el formulario dos veces se le cobra una.
- **Los reintentos son seguros** con una [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md).

Consulta [Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md) para la lista completa y [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md) para los límites de peticiones.
