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

Consulta Veredictos y reason codes para la lista completa y Límites y errores para los límites de peticiones.

Ver esta página en Markdown