Verificación de emails con node.js

De vez en cuando, las personas de tu lista de contactos pueden cambiar de trabajo o de proveedor de servicios de envío de emails. Cuando esto ocurre, sus emails también cambian, dejando direcciones inválidas en tu lista. Estos emails inválidos pueden provocar tasas de rebote altas, lo que perjudica tu reputación como remitente y aumenta las probabilidades de acabar en una lista de bloqueo por spam.

La validación de emails ayuda a evitar los emails inválidos, ya que garantiza que tus emails lleguen a bandejas de entrada reales y activas. Al verificar regularmente las direcciones de email, reduces las probabilidades de que reboten, proteges tu reputación ante los proveedores de servicios de internet (ISP) y aumentas la entregabilidad general de tus campañas.

Si buscas validar un lote de direcciones de email, Mailgun ofrece una API de validación de emails masiva que puede ayudarte exactamente con eso. En este tutorial, aprenderás a verificar de forma eficiente listas grandes de direcciones de email en Node.js aplicaciones con Mailgun y a integrar el proceso en tu aplicación para asegurar una alta entregabilidad.

Para seguir este tutorial, necesitarás lo siguiente:

• Conocimientos básicos de Node.js
• Un Cuenta de Mailgun; para usar la validación de emails masiva, debes tener una cuenta de pago

Para verificar emails con Node.js usando la API de Mailgun, tienes que crear una lista de contactos y añadir los emails que quieres validar. Luego, puedes iniciar un trabajo de validación en la lista de contactos y recuperar los resultados. Pero, antes de poder hacer solicitudes a la API de Mailgun, necesitas los datos de autenticación de tu panel de control. También debes configurar y verificar un dominio personalizado para crear una lista de contactos.

La API de Mailgun autoriza las solicitudes mediante HTTP Basic Auth, lo que requiere que incluyas un nombre de usuario y una contraseña en el encabezado Authorization. Para obtener los datos necesarios, inicia sesión en tu cuenta de Mailgun, haz clic en el icono desplegable de la parte superior derecha de la pantalla y haz clic en API Security en el menú:

En la página API Security, haz clic en el botón Add new key para mostrar un modal con un formulario. Rellena la descripción en el formulario, haz clic en Create Key, copia la clave de API y guárdala de forma segura; es tu contraseña y solo podrás verla una vez:

A continuación, puedes optar por añadir un dominio personalizado a tu cuenta de Mailgun y verificarlo. Este paso es opcional y solo es necesario en entornos de producción. Para este tutorial, usarás el dominio predeterminado que proporciona Mailgun, el cual puedes encontrar yendo a Send > Sending > Domains:

Anota el nombre del dominio predeterminado; lo necesitarás para crear una lista de contactos.
Después de recuperar tus datos de autenticación y añadir un dominio personalizado (o anotar el predeterminado), es hora de configurar un entorno de desarrollo de Node.js donde harás solicitudes a la API de Mailgun.

Para configurar un entorno de desarrollo de Node.js, primero crea un nuevo directorio de proyecto y accede a él ejecutando el siguiente comando:

                                

                                    mkdir bulk-email-validation && cd bulk-email-validationrnThen, initialize npm in your project by running this command:rnnpm init -yrnRun the following command to install the required dependencies:rnnpm install axios dotenv form-datarn
                                
                            

Las dependencias instaladas incluyen las siguientes:

• Axios: es una biblioteca que te permite enviar solicitudes y recibir respuestas de una API. Usarás Axios para comunicarte con la API de Mailgun.
• Dotenv: es una biblioteca que carga variables de entorno en process.env. La usarás para gestionar tus datos de autenticación de forma segura.
• Form-Data: es una biblioteca que crea flujos legibles multipart/form-data. La API de Mailgun solo acepta datos en formato multipart/form-data, así que necesitas esta biblioteca para enviar formularios a la API.

Después de instalar estas dependencias, crea un archivo index.js y un archivo .env. En tu archivo .env, guarda las siguientes variables y sustituye los marcadores de posición por sus valores reales:

                                

                                    MAILGUN_USERNAME = apirnMAILGUN_PASSWORD = <API_KEY>rnThe value of your username must be api.rnIn your index.js file, add the following code block to import all the required dependencies and initialize dotenv:rnconst axios = require("axios");rnconst FormData = require("form-data");rnconst fs = require("node:fs");rnconst dotenv = require("dotenv");rndotenv.config();
                                
                            

Este bloque de código importa las dependencias necesarias para hacer solicitudes a la API de Mailgun. Además de los paquetes que has instalado antes, las importaciones incluyen el módulo fs de Node.js, que necesitas para crear un flujo legible hacia el archivo que contiene tu lista de contactos.
Ahora que tu entorno de desarrollo está listo, puedes validar direcciones de email en una lista de contactos.

Como se ha mencionado en los requisitos previos, para usar el servicio de validación de emails masiva con Mailgun, debes tener una cuenta de pago.

Para crear un trabajo de validación con la API de Mailgun, tienes que hacer una solicitud POST a https://api.mailgun.net/v4/address/validate/bulk/${listId}, donde listId es un valor arbitrario que asignas al trabajo de validación.

Este punto de conexión acepta un formulario con un archivo CSV que contenga las direcciones de email que quieres validar. El encabezado de la columna del archivo CSV para los emails debe ser email o email_address, y el formato tiene que ser CSV sin formato o gzip. Puedes incluir un número ilimitado de direcciones de email en el archivo; sin embargo, el tamaño del archivo no puede superar los 25 MB.

La clave del formulario para el archivo CSV debe ser file, y el valor tiene que ser un flujo legible hacia la ruta de tu archivo CSV.

Puedes añadir el siguiente bloque de código a tu archivo index.js para implementar una función que cree un trabajo de validación de emails masiva:

                                

                                    const createBulkValidationJob = async (listId) => {rn  try {rn    // Create a new form data objectrn    const form = new FormData();rnrn    // Add the file to the formrn    form.append("file", fs.createReadStream("PATH_TO_CSV_FILE"));rnrn    const response = await axios.post(rn      `https://api.mailgun.net/v4/address/validate/bulk/${listId}`,rn      form,rn      {rn        headers: {rn          ...file.getHeaders(),rn          Authorization:rn            "Basic " +rn            Buffer.from(rn              `${process.env.MAILGUN_USERNAME}:${process.env.MAILGUN_PASSWORD}`rn            ).toString("base64"),rn        },rn      }rn    );rnrn    console.log(response.data);rn  } catch (error) {rn    console.error(error);rn  }rn};rnCalling this function with a listId should return a response similar to this:rn{rn  id: 'validation', // Arbitrary value you assigned to the validation jobrn  message: 'The validation job was submitted.'rn}
                                
                            

Validar una lista de contactos lleva su tiempo; para obtener los resultados de la validación, tienes que hacer una solicitud a la API con el id de tu trabajo de validación.

Para obtener los resultados de un trabajo de validación, tienes que hacer una solicitud GET a https://api.mailgun.net/v4/address/validate/bulk/${listId}, donde listId es el id que asignaste a tu trabajo de validación.

Añade el siguiente bloque de código a tu archivo index.js para implementar una función que recupere los resultados de la validación:

                                

                                    const getValidationResults = async (listId) => {rn  try {rn    const response = await axios.get(rn      `https://api.mailgun.net/v4/address/validate/bulk/${listId}`,rn      {rn        headers: {rn          Authorization:rn            "Basic " +rn            Buffer.from(rn              `${process.env.MAILGUN_USERNAME}:${process.env.MAILGUN_PASSWORD}`rn            ).toString("base64"),rn        },rn      }rn    );rnrn    console.log(response.data);rn  } catch (error) {rn    console.error(error);rn  }rn};rnCalling this function with a listId should return a response like this:rn{rn  created_at: 1728170695,rn  download_url: {rn    "csv": "https://s3.aws-example.com/downloads/bulk_validation_oct_2024.csv.zip",rn    "json": "https://s3.aws-example.com/downloads/bulk_validation_oct_2024.json.zip"rn  },rn  id: 'validation',rn  quantity: 10,rn  records_processed: 10,rn  status: 'uploaded',rn  summary: {rn    result: {rn      catch_all: 0,rn      deliverable: 3,rn      do_not_send: 0,rn      undeliverable: 1,rn      unknown: 6rn    },rn    risk: { high: 1, low: 3, medium: 0, unknown: 6 }rn  }rn}
                                
                            

• created_at: marca de tiempo que indica cuándo se completó el trabajo (1728170695).
• download_url: enlaces para descargar los resultados en los formatos CSV y JSON.
• Quantity: el número total de emails procesados (10).
• Status: el estado del trabajo de validación (uploaded).
• Result: el resultado de la validación de emails:
• catch_all: ninguna dirección procede de dominios catch-all.
  • deliverable: tres direcciones son válidas y entregables.
  • do_not_send: ninguna dirección está marcada como «do not send».
  • undeliverable: una dirección es inválida o no entregable.
  • unknown: seis direcciones no se han podido verificar.
• Risk: un desglose de las direcciones de email por nivel de riesgo:
  • high: una dirección es de alto riesgo y probablemente no entregable o problemática.
  • low: tres direcciones se consideran de bajo riesgo y seguras de usar.
  • medium: ninguna dirección es de riesgo medio que pueda requerir precaución.
  • unknown: seis direcciones no se han podido clasificar.

Al usar la API de Mailgun para la validación de emails masiva, puedes encontrarte con algunos errores comunes. A continuación, te mostramos un desglose de estos errores y algunos consejos para solucionarlos:

• List already exists: este error con código de estado 409 indica que ya existe un trabajo de validación con el mismo listId que el que intentas crear. Puedes solucionar este error cambiando el listId y volviendo a intentar la solicitud.
• List CSV file missing: este error con código de estado 400 indica que la API no ha podido encontrar el archivo CSV en tu solicitud porque estás usando la clave del archivo incorrecta. Asegúrate de que la clave de tu archivo esté configurada como file y vuelve a intentarlo.
• CSV File must contain the key email or email_address: este error con código de estado 400 indica que a tu archivo CSV le falta el encabezado de columna email o email_address. Puedes solucionar este error editando tu archivo CSV para que contenga cualquiera de estos encabezados.
• CSV file is malformed: este error con código de estado 400 indica que tu archivo está en un formato no compatible. Asegúrate de que el archivo que contiene tus emails esté en formato CSV o gzip.
• unauthorized: este error con código de estado 401 indica que hay un problema con tus credenciales de autenticación. Puedes solucionarlo asegurándote de que tus claves de API son válidas.

Para asegurarte de que tus trabajos de validación de emails masiva funcionen como se espera, aquí tienes algunas mejores prácticas que puedes seguir:

• Respect API limits: asegúrate de respetar los límites impuestos por la API de Mailgun para garantizar que se procesen todas tus solicitudes. Por ejemplo, los archivos CSV no deben superar los 25 MB; los archivos de mayor tamaño provocarán una respuesta 400. Además, el número máximo de trabajos de validación que pueden ejecutarse en paralelo es de cinco. Superar este límite dará lugar a una respuesta 400.
• Use batching to avoid API limits: si validas un conjunto de datos grande de emails, agrúpalos en lotes para gestionar el tamaño del archivo, pero ten cuidado con los límites de procesamiento en paralelo.
• Check for specific status codes: los distintos errores requieren diferentes estrategias de gestión. Por ejemplo, un 400 Bad Request probablemente indique un problema con el formato de la solicitud; no vuelvas a intentarlo. En su lugar, registra el error y corrige la solicitud. Un 500 Internal Server Error indica un problema en el lado del servidor y puedes volver a intentarlo después de un periodo de espera.

En este tutorial, has explorado cómo verificar emails usando Node.js y la API de Mailgun. Has aprendido a crear listas de contactos, añadir miembros a esas listas y validar las direcciones de email de forma masiva.

La validación de emails masiva y regular puede mejorar de forma significativa tus tasas de entregabilidad del email, mantener una lista de contactos limpia y efectiva, asegurar que tus mensajes lleguen a sus destinatarios previstos y ayudarte a conservar una buena reputación como remitente.

Autor: David Ekete Software developer, technical writer, and JavaScript / TypeScript developer with a growing interest in exploring and contributing to emerging technology.