Guía de producto
API de verificación de correo: Cómo elegir entre solicitudes individuales, múltiples y masivas
Guía para desarrolladores sobre cómo elegir entre verificaciones individuales, múltiples y masivas, y cómo integrar los resultados en su lógica de aplicación.
Cómo elegir la solicitud de API de verificación de correo adecuada para cada tarea y asignar los resultados de Entregable, No entregable e Indeterminado al código.
Una API de verificación de correo debe invocarse en una de tres modalidades, según quién espere la respuesta y cuántas direcciones tenga. Utilice una verificación individual (POST /api/v1/check) cuando una persona espera por una sola dirección, una verificación múltiple síncrona (POST /api/v1/batch-check, de 1 a 100 direcciones, resultados en el orden de entrada) cuando llega un grupo pequeño, y una tarea masiva asíncrona (POST /api/v1/bulk-tasks, seguida de sondeo de estado) cuando las direcciones ya están en un archivo. Independientemente de la modalidad, diseñe su código en torno a tres resultados en lugar de un indicador de sí/no: Entregable, No entregable e Indeterminado, gestionando las entradas mal formadas antes de realizar la llamada. Cada resultado completado describe la dirección únicamente en el momento de la verificación.
Qué responde una API de verificación de correo y qué queda bajo su responsabilidad
La mayoría de las páginas que aparecen en los resultados de búsqueda sobre este tema enumeran funciones y se detienen ahí. La cuestión de la integración es más específica: ¿qué decide realmente una llamada y de qué sigue siendo responsable su aplicación?
La Verificación de entregabilidad de correo de EmailCheckPro devuelve un resultado completado de Entregable (la dirección podía recibir correo en el momento de la verificación) o No entregable. La Verificación de avatar de correo añade una señal de avatar público, pero solo para direcciones de Gmail, Yandex y Mail.ru.
Su aplicación sigue siendo responsable de tres tareas:
- Filtrado de formato. Una dirección completa tiene una parte local, un signo
@y un dominio. Una entrada mal formada es un error de formulario, no un veredicto de No entregable, así que detéctela antes de realizar una llamada. - Un enlace de confirmación o sus propios registros de consentimiento cubren ese aspecto.
- Temporización. Un resultado pertenece al momento de la verificación. Guarde la fecha junto al resultado para que las tareas posteriores sepan qué antigüedad tiene.
Mantener estos límites en el código, y no solo en la documentación, evita los errores de integración más comunes descritos a continuación.
Elección de la modalidad de solicitud de la API de verificación de correo
Las tres modalidades de solicitud no son intercambiables, y elegir la incorrecta es la causa habitual de formularios lentos o trabajos de importación frágiles.
| Situación | Solicitud | Cómo llegan los resultados | A tener en cuenta |
|---|---|---|---|
| Un formulario de registro, pago o perfil | POST /api/v1/check |
En la misma respuesta | Mantenga la llamada en el lado del servidor y establezca su propio tiempo de espera |
| Un administrador pega una lista corta, o un trabajo procesa registros editados desde la última ejecución | POST /api/v1/batch-check (1–100 direcciones) |
En la misma respuesta, en el orden de entrada | Los elementos sin un resultado completado no son No entregable |
| Una exportación de CRM, una migración de lista o cualquier archivo preparado | POST /api/v1/bulk-tasks, luego GET /api/v1/bulk-tasks/{id} |
Más tarde, como un archivo CSV de resultados | No realice sondeos con una frecuencia superior a 30 segundos |
Una forma rápida de decidir:
- ¿Hay alguien esperando en pantalla? Utilice el endpoint individual solo para la dirección que escribió.
- ¿Las direcciones llegan juntas y son menos de 100? Envíe una solicitud múltiple. Sigue siendo síncrona: una llamada individual más grande, no una tarea masiva pequeña.
- ¿La fuente ya es un archivo o supera con creces unos cientos de filas? Envíe una tarea masiva y deje que un proceso en segundo plano recopile el resultado. Se aplican límites de tarea por producto, los cuales se enumeran en la documentación de la API.
- ¿El trabajo necesita avatares? Filtre primero la lista para incluir solo dominios compatibles de Gmail, Yandex y Mail.ru. Un dominio no compatible se rechaza antes de realizar un cargo en tiempo real, y en un archivo masivo de avatares provoca un error en la preparación, devolviendo la reserva.
Para unos pocos cientos de direcciones que no están en un archivo, es razonable utilizar varias solicitudes múltiples o la verificación en tiempo real del panel de control, que admite hasta 500 direcciones.
Asignación de resultados a la lógica de la aplicación
Colapsar los resultados en un valor booleano es donde fallan la mayoría de las integraciones. Un pequeño tipo de estado mantiene el significado intacto:
| Estado | Fuente | Formulario de registro | Tubería de importación o envío |
|---|---|---|---|
| Malformado | Su propia verificación de formato | Solicite una corrección en línea | Mueva la fila a una cola de corrección |
| Entregable | Verificación completada | Continuar | Conservar, con la fecha de verificación |
| No entregable | Verificación completada | Solicite otra dirección, ofrezca un reintento | Suprima los envíos rutinarios y busque una dirección actual |
| Indeterminado | La verificación no pudo resolverse, por ejemplo, una dirección Catch-All | Aceptar con un indicador | Mantener en un grupo de revisión y volver a verificar más tarde |
| No completado | Tiempo de espera, error de red o fallo del servicio | Aceptar con un indicador | Reintentar más tarde desde una cola |
De la documentación se derivan tres reglas:
- En una verificación individual en tiempo real, una dirección Indeterminado devuelve un código de negocio en lugar de un resultado y no se cobra. Trate esa rama como su propio estado, no como un error que deba reintentar en un bucle cerrado.
- En una respuesta múltiple, cada elemento indica si existe un resultado completado. Solo los elementos que lo tienen son Entregable o No entregable; el resto pertenece a la rama de Indeterminado o No completado.
- Las verificaciones Inválidas, fallidas e Indeterminado no se cobran, por lo que reintentarlas más tarde no cuesta nada más que tiempo. Programe el reintento en lugar de repetirlo inmediatamente.
Ejecución de tareas masivas asíncronas sin sorpresas
Una tarea masiva es una pequeña máquina de estados y debe residir en un proceso en segundo plano, no en una solicitud web.
- Prepare el archivo. Escriba un archivo TXT o CSV con una dirección de correo electrónico completa por línea. Las líneas inválidas y duplicadas se eliminan durante la preparación, pero eliminar la basura obvia primero facilita la conciliación de sus propios conteos.
- Envíe y registre. Guarde la referencia de la tarea devuelta por
POST /api/v1/bulk-tasksen su base de datos, junto con el nombre del archivo de origen, el producto utilizado y la hora de envío. Un proceso que falle podrá reanudarse en lugar de tener que reenviar todo. - Realice sondeos con paciencia. Consulte
GET /api/v1/bulk-tasks/{id}con una frecuencia no superior a 30 segundos. Un trabajo programado que verifica una vez y espera se ajusta mejor a esto que un bucle que mantiene una conexión abierta. - Descargue con prontitud. Una tarea exitosa proporciona un CSV en un enlace de descarga que dura 12 horas. Si el enlace caduca, consulte la misma tarea de nuevo para obtener un enlace nuevo en lugar de subir el archivo por segunda vez.
- Combine por dirección. Debido a que la preparación puede eliminar líneas, unaa el CSV de resultados con sus registros por dirección de correo electrónico, nunca por número de fila.
El CSV de entregabilidad empareja cada dirección con su resultado. El CSV de avatares también indica si se encontró un avatar público y proporciona un enlace al mismo, el cual puede estar vacío incluso cuando hay un avatar presente, así que trate un enlace vacío como un valor normal.
Operación diaria de la integración
Una vez que las modalidades de solicitud y los estados son correctos, algunos hábitos operativos mantienen la integración estable:
- Solo claves del lado del servidor. La clave de API consume el saldo de la cuenta, el cual es compartido por verificaciones web, llamadas REST, tareas masivas y acceso MCP. Nunca la incluya en código de navegador o móvil.
- Verifique en el punto de cambio. Verifique cuando se crea o edita una dirección, luego reutilice el resultado almacenado dentro de su propia ventana de re-verificación en lugar de llamar en cada vista de página.
- Falle abierto en el formulario, cerrado en la tubería. Si una verificación es lenta o no está resuelta durante el registro, permita que la persona continúe con una dirección marcada. En una tubería de envío, retenga las filas marcadas hasta que tengan un resultado completado.
- Proteja su propio endpoint. Si su aplicación expone una ruta de "verificar esta dirección", limite su tasa y devuelva mensajes consistentes. La guía de validación de correo de OWASP advierte contra permitir que los formularios revelen si una cuenta existe.
- Proporcione a los clientes de IA el endpoint MCP.
https://emailcheckpro.com/mcpadmite verificaciones individuales, hasta 100 direcciones por llamada, listado de productos y consultas de saldo. El trabajo masivo basado en archivos permanece en el flujo de trabajo web o en la API REST.
Los límites de solicitud actuales y los detalles de uso se publican en la documentación de la API de EmailCheckPro; léalos allí en lugar de codificar suposiciones.
Una verificación de formato que coincide con las expectativas de la API
La llamada más barata es la que nunca realiza para una entrada mal formada. Dos referencias le ayudan a elegir un filtro sensato:
- El estándar HTML de WHATWG define el patrón que utilizan los navegadores para los campos
type="email". Se aparta deliberadamente de los estándares completos de correo para seguir siendo práctico, lo que lo convierte también en una base razonable para el lado del servidor. - RFC 5321 describe las formas de dirección utilizadas en el transporte de correo. Trátelo como una referencia de formato para casos extremos, como partes locales entre comillas, no como una descripción de cómo funciona un servicio de verificación.
En la práctica: elimine los espacios en blanco, elimine la puntuación final copiada de documentos, convierta el dominio a minúsculas, mantenga la parte local tal como se ingresó y rechace solo la entrada que claramente carezca de una parte local, un @ o un dominio. Los patrones demasiado estrictos que rechazan signos más o dominios de nivel superior largos alejan a usuarios reales y deben evitarse.
Preguntas frecuentes
¿Cuándo deberían los equipos cambiar de llamadas de múltiples direcciones a una tarea masiva?
Cambie cuando las direcciones ya residan en un archivo, o cuando un trabajo necesite muchas llamadas múltiples consecutivas solo para procesar una lista. Las solicitudes múltiples se adaptan a grupos de hasta 100 que llegan juntos y necesitan respuestas en la misma respuesta. Las tareas masivas se adaptan a exportaciones preparadas que pueden esperar, porque el resultado llega más tarde como un CSV y el proceso solo necesita sondear el estado cada 30 segundos o menos.
¿Cómo debe una aplicación almacenar los resultados de la API de verificación de correo?
Mantenga la dirección tal como se ingresó, el producto utilizado, el resultado en palabras claras, la fecha de verificación y la fuente de la dirección. Ese registro permite al soporte explicar una decisión, permite que los trabajos de re-verificación elijan primero los resultados más antiguos y mantiene las filas Indeterminado o No completado separadas de las No entregable. Evite almacenar cargas útiles de respuesta sin procesar como único registro, ya que otros sistemas dependerían entonces del formato de la API.
¿Puede un resultado Entregable reemplazar un correo electrónico de confirmación?
No. Un resultado Entregable informa si la dirección podía recibir correo en el momento de la verificación, y la verificación en sí no envía nada. Un enlace de confirmación responde a una pregunta diferente: si la persona que ingresó la dirección la controla y acepta recibir mensajes. Muchos flujos de registro utilizan la verificación para detectar direcciones muertas antes de enviar, y luego confían en la confirmación para el consentimiento y la propiedad.
¿Cuál es la forma más segura de reintentar verificaciones que no se completaron?
Colóquelas en una cola con un retraso en lugar de reintentar en la solicitud que falló. Las verificaciones Indeterminado, fallidas e inválidas no se cobran, pero los reintentos inmediatos rara vez cambian el resultado y pueden ralentizar su propio servicio. Un reintento programado, con un límite de intentos y una nota de la fecha de cada intento, mantiene el registro honesto y permite a los revisores ver qué direcciones aún no tienen un resultado completado.
Más información
Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.