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
- El formulario envía los datos a tu servidor. La clave de API nunca llega al navegador.
- Tu servidor llama a
POST /verifycon"mode": "basic"y un tiempo de espera corto. - Rechaza los
invalid, aplica tu política a los dominios desechables y acepta el resto. - Si la llamada falla o se agota el tiempo, acepta el registro y verifica después.
- Envía tu email de confirmación como siempre.
// 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, un402o un5xxnunca deben costarte un usuario real. Acepta y verifica después. - Nunca trates
unknowncomoinvalid. En modobasic,unknownes la respuesta para cualquier dominio sano. - Mantén tu email de confirmación.
validdice 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
basices 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.