Verificación masiva de correos electrónicos con API: un flujo de trabajo práctico por lotes

Verificación masiva de correos electrónicos con API: un flujo de trabajo práctico por lotes

La pregunta: Tienes una lista grande de direcciones en tu propio sistema. ¿Cómo la envías por lotes a través de la API de FairValid, gestionas los errores de forma segura y recuperas los resultados sin perder el control de los créditos?

Respuesta breve: Empieza en el sandbox con una clave de prueba (Test). Después, divide la lista en trabajos de hasta 5.000 direcciones y asigna a cada trabajo su propia clave de idempotencia. Envía cada trabajo con una clave real (Live), comprueba su estado y recorre los resultados página a página según el resultado. Trata las comprobaciones pendientes, los fallos técnicos y los resultados Desconocido como tres situaciones distintas.

Información verificada el 13 de noviembre de 2026 con la referencia de la API, la guía de resultados y las reglas de créditos de FairValid.

Paso 1: desarrolla primero contra el sandbox

La referencia de la API indica que debes crear una clave de prueba en Claves de API, guardarla en tu servidor y configurarla en tu entorno junto con la URL base. Las claves de prueba funcionan con direcciones reservadas del dominio example.com. No realizan llamadas a proveedores ni consumen créditos. Las claves de prueba acceden a sus propios trabajos simulados.

Los trabajos de prueba devuelven estados deterministas: completado, pendiente, fallido o cancelado. Consulta la referencia de la API para conocer las direcciones exactas del sandbox y úsalas para confirmar que tu código gestiona estos estados. Estos casos solo muestran los resultados para los que se diseñaron. No cubren todas las ramas de tu integración, así que revisa por separado tus propias rutas de error.

Paso 2: pasa a una clave real con los permisos adecuados

Para producción, la referencia de la API indica que necesitas una clave real con el permiso submit para crear trabajos. Añade el permiso read para leer el estado y los resultados de los trabajos. Las claves reales también pueden tener el permiso balance. El secreto completo de la clave solo se muestra una vez, así que guárdalo de forma segura en tu servidor al crearla. Una clave revocada deja de aceptar nuevas solicitudes.

Los trabajos reales usan la cola de verificación y el saldo de créditos de tu espacio de trabajo. Los permisos y límites de la clave, el acceso al espacio de trabajo y los límites de procesamiento siguen aplicándose. Una clave real no te da acceso ilimitado.

Paso 3: divide la lista y envía los trabajos

Cada trabajo acepta de 1 a 5.000 direcciones en JSON, con un máximo de 2 MiB. Este es un enfoque práctico:

1. Divide tu lista en bloques. Por ejemplo, 12.000 direcciones se convertirían en tres trabajos de 5.000, 5.000 y 2.000.
2. Asigna a cada bloque su propia Idempotency-Key estable y registra qué filas tuyas fueron a cada bloque. Mantener esa correspondencia en tu lado facilita vincular los resultados con tus registros.
3. Envía al endpoint de trabajos. Un trabajo nuevo devuelve HTTP 202 con un job_id UUID. Un reintento equivalente devuelve HTTP 200 con el mismo trabajo. Esto significa que, tras un tiempo de espera agotado, puedes reenviar la misma solicitud con la misma clave y recuperar el trabajo existente.

Paso 4: gestiona los dos errores que se parecen

Ambas respuestas pueden bloquear un envío, pero significan cosas distintas:

• HTTP 503 live_verification_unavailable puede devolverse durante una pausa operativa. Según la referencia de la API, esto ocurre sin retener créditos. Vuelve a intentarlo más tarde con la misma Idempotency-Key.
• HTTP 402 key_cap_reached significa que una nueva solicitud superaría el límite de gasto total de la clave. Ese límite suma los créditos ya cobrados más los créditos reservados para identidades únicas aceptadas. No se crea ningún trabajo ni retención. Un límite total no se recarga con el tiempo, así que esperar no lo soluciona. Revisa el límite de la clave en la configuración de claves de API o usa una clave con suficiente límite restante para el trabajo. Además, el límite de una clave no puede añadir créditos al espacio de trabajo. Solo limita lo que esa clave puede gastar.

Registra estas dos respuestas por separado de los errores de permisos y de los límites de procesamiento, para que la persona adecuada reciba la alerta adecuada.

Paso 5: sigue el estado del trabajo y luego pagina los resultados

El endpoint del trabajo devuelve su estado actual y un resumen. El estado puede ser en cola, en ejecución, en pausa, cancelándose, cancelado o completado. Si solicitas la cancelación, el trabajo que ya esté en curso puede terminar igualmente.

El endpoint de resultados devuelve hasta 50 resultados cada vez, junto con un next_cursor firmado. Pasa ese valor como parámetro de consulta cursor. Conserva tu filtro y tu búsqueda originales. Los filtros son all, valid, invalid, catch_all, unknown, still_checking y not_checked. Puedes usarlos para obtener solo las filas que requieren una decisión, como todo lo marcado como unknown.

Paso 6: convierte los resultados en decisiones

La guía de resultados describe los resultados como indicios, no como una garantía de entrega:

• Válido indica una comprobación positiva utilizable. Nunca garantiza la entrega en la bandeja de entrada.
• No válido significa que la dirección no superó la comprobación.
• Catch-all significa que el dominio puede aceptar muchas direcciones, por lo que una conclusión sobre el buzón concreto puede ser menos fiable. Lee el detalle antes de usar la dirección.
• Desconocido significa que la comprobación no pudo dar una respuesta fiable.
• Aún en comprobación significa que todavía no hay una respuesta definitiva. Sigue consultando y no lo trates como Desconocido.

Los fallos técnicos y los elementos sin procesar son una categoría aparte. Las reglas de créditos de FairValid indican que no se reclasifican como Desconocido.

Paso 7: entiende las reservas de créditos

La referencia de la API indica que los créditos del espacio de trabajo se reservan a medida que las comprobaciones se admiten para su procesamiento. Los resultados siguen las mismas reglas de cobro y devolución que el panel. Según las reglas de créditos, un resultado Válido o No válido completado cuesta un crédito. Los resultados Desconocido y Catch-all sin resolver no acaban descontando ningún crédito, porque los créditos retenidos se liberan o se devuelven. Pendiente no es un resultado final. Los fallos técnicos y el trabajo sin procesar tampoco acaban descontando créditos. Los créditos devueltos conservan el lote y las reglas de caducidad que tenían originalmente.

El endpoint de saldo informa de los créditos disponibles y retenidos del espacio de trabajo real. Cuando su campo free_allowance_held es true, la asignación gratuita está retenida y no se cuenta en available_credits ni en free_available. Los créditos de pago siguen disponibles. La cuenta original recibe 300 créditos gratuitos cada mes en la fecha de su registro, y los créditos gratuitos no usados no se acumulan para el periodo siguiente. Los espacios de trabajo adicionales no reciben una asignación gratuita extra. Los créditos gratuitos se usan primero, y los créditos de pago no caducan mientras la cuenta siga abierta.

Una lista de comprobación sencilla

• Haz pruebas con una clave de prueba y los casos de sandbox documentados.
• Usa una clave real con los permisos submit y read, y un límite adecuado para el trabajo previsto.
• Limita cada bloque a 5.000 direcciones o menos, con una clave de idempotencia estable por bloque.
• Reintenta un 503 más tarde con la misma clave. No esperes a que se resuelva un 402; ocúpate del límite.
• Recorre los resultados con el cursor firmado, filtrados por resultado.
• Mantén separados en tus datos los pendientes, los fallos técnicos y los Desconocido.

Si quieres probar este flujo de trabajo, puedes crear una clave de prueba y ejecutar un trabajo en el sandbox sin consumir créditos antes de tu primer envío real. La referencia de la API incluye todos los detalles de los endpoints.