La mejor API de verificación es la que aguanta bajo carga.

Va a ramificar sobre este objeto durante años, así que léalo antes que nada. Un esquema con un único campo enumerado obliga a cada consumidor a reconstruir el matiz que el proveedor ya tenía y tiró.

Lo que quiere es un veredicto sobre el que hacer un switch, una puntuación numérica cuyo umbral fija usted, y motivos legibles por máquina debajo de ambos. Esos motivos son los que permiten tratar de forma distinta una dirección de rol, un buzón lleno y un dominio que le aplicó greylisting, sin tres integraciones separadas.

• Un veredicto de accesibilidad, estable entre versiones, que se proyecte limpiamente sobre permitir, avisar y bloquear
• Una puntuación, para que su umbral sea un valor de configuración y no una decisión del proveedor
• Códigos de motivo documentados y enumerables, no texto libre en inglés
• Una acción recomendada, útil para las partes del producto que no son código
• Marcas para las condiciones que le importan: captura total, desechable, rol, sugerencias de errata

La verificación a nivel de buzón habla con un tercero por SMTP, y algunos servidores de destino son lentos a propósito. Una comprobación suelta suele ser rápida y a veces no lo es, lo que es un problema si está en la ruta crítica de un registro.

Diséñelo para eso en lugar de confiar en la suerte. Fije un tiempo de espera en cliente que le parezca aceptable mostrar, trate el vencimiento como sin conclusión y no como inválido, y deje pasar el registro con una marca en vez de rechazar a un cliente real porque un servidor estaba ocupado. Después vuelva a comprobar de forma asíncrona y actúe con la segunda respuesta.

Pida a cualquier proveedor su tiempo de espera publicado y qué hace al alcanzarlo. Quien devuelve inválido en su propio vencimiento está convirtiendo en silencio su problema de infraestructura en el registro que usted pierde.

Hay tres clases de fallo y piden tres reacciones distintas de su código. Confundirlas es la causa más común de que una integración de verificación se tuerza en producción.

Una petición mal formada es un fallo suyo y nunca debe reintentarse. Un límite de tasa o un fallo transitorio aguas arriba se reintenta con espera creciente. Y un veredicto sin conclusión no es un error: la llamada tuvo éxito, la respuesta es que no había respuesta disponible, y reintentar de inmediato producirá la misma no respuesta gastando otro crédito.

• 4xx para sus errores, con un código estable y legible por máquina, no una frase
• 429 con una cabecera que diga cuándo volver, en vez de una negativa seca
• 5xx solo para fallos del proveedor, para que su monitorización pueda fiarse
• Resultados sin conclusión devueltos como 200 con veredicto desconocido, porque eso es lo que pasó

Una comprobación suelta es síncrona y vive en una petición. Un lote es asíncrono y vive en una cola, a veces durante una hora. Tratar lo segundo como lo primero es acabar consultando un endpoint de estado cada segundo durante cuarenta minutos.

Compruebe que el lado de los lotes es una API de trabajos de verdad: enviar, recibir un id, consultar o recibir una llamada de retorno, y descargar. Compruebe qué pasa si envía el mismo fichero dos veces, cuál es el techo de tamaño y si la exportación conserva sus columnas. Esas tres respuestas ahorran más tiempo de ingeniería que la diferencia de precio entre dos proveedores de este mercado.

Ninguno es interesante hasta el día en que lo es, y para entonces la integración ya está escrita.

• Rotación de claves. Más de una clave activa, revocables por separado, sin caída.
• Nunca llame a una API de verificación desde el navegador. La clave es un secreto, y una clave pública es el saldo de créditos de otro.
• Conservación. Cuánto tiempo se guarda la dirección que envió, y si puede acortarlo.
• Idempotencia al enviar un lote, para que un corte de red no le facture dos veces el mismo fichero.
• Si el mismo motor está detrás del panel y de la API. Si no, su comprobación puntual no demuestra nada sobre producción.

Un token, un endpoint para una dirección y otro para un lote. POST /v1/check_email devuelve el veredicto, la puntuación, los códigos de motivo y la acción recomendada; POST /v1/bulk recibe una lista y devuelve un trabajo que se consulta. Ambos están documentados con ejemplos ejecutables en vez de un volcado de esquema.

Las claves de API vienen con cualquier plan de pago, mensual o por uso, en lugar de empezar en un nivel que la mayoría de equipos no necesita. Una cuenta gratuita verifica en el panel, lo bastante para ver la forma de la respuesta antes de escribir código.