Verificando e-mails com Node.js

De tempos em tempos, as pessoas na sua lista de e-mails podem mudar de emprego ou provedor de serviços de e-mail. Quando isso acontece, os e-mails delas também mudam, deixando endereços inválidos na sua lista. Esses e-mails inválidos podem levar a altas taxas de devolução, o que prejudica a reputação do remetente e aumenta a chance de entrar em uma lista de bloqueio de spam.

A validação de e-mail ajuda a evitar e-mails inválidos, garantindo que cheguem a caixas de entrada reais e ativas. Ao verificar endereços de e-mail regularmente, você reduz as chances de devolução, protege sua reputação com os ISPs (provedores de serviços de internet) e aumenta a entregabilidade geral das suas campanhas.

Se você quer validar um lote de endereços de e-mail, Mailgun oferece uma API de validação de e-mail em massa que pode ajudar com isso. Neste tutorial, você aprenderá a verificar de forma eficiente grandes listas de endereços de e-mail em Node.js aplicativos com o Mailgun e a integrar o processo ao seu aplicativo para garantir alta entregabilidade.

Para acompanhar este tutorial, você precisará de:

• Conhecimento básico de Node.js
• Um conta do Mailgun; para usar a validação de e-mail em massa, você precisa ter uma conta paga

Para verificar e-mails com Node.js usando a API do Mailgun, crie uma lista de e-mails e adicione os e-mails que deseja validar. Em seguida, você pode iniciar um trabalho de validação na lista de e-mails e recuperar os resultados. Porém, antes de fazer solicitações à API do Mailgun, você precisa dos seus detalhes de autenticação do painel. Você também precisa configurar e verificar um domínio personalizado para criar uma lista de e-mails.

A API do Mailgun autoriza solicitações usando HTTP Basic Auth, o que exige que você inclua um nome de usuário e uma senha no cabeçalho Authorization. Para obter os detalhes necessários, faça login na sua conta do Mailgun, clique no ícone de menu suspenso no canto superior direito da tela e clique em “API Security” no menu:

Na página “API Security”, clique no botão “Add new key” para revelar um modal com um formulário. Preencha a descrição no formulário, clique em “Create Key”, copie a chave de API e guarde-a com segurança; essa é a sua senha e você só pode vê-la uma vez:

Em seguida, você pode optar por adicionar um domínio personalizado à sua conta do Mailgun e verificá-lo. Esta etapa é opcional e necessária apenas em ambientes de produção. Para este tutorial, você usará o domínio padrão fornecido pelo Mailgun, que pode ser encontrado acessando “Send > Sending > Domains”:

Anote o nome de domínio padrão; você precisará dele para criar uma lista de e-mails.
Após recuperar os detalhes de autenticação e adicionar um domínio personalizado (ou anotar o padrão), é hora de configurar um ambiente de desenvolvimento Node.js onde você fará solicitações à API do Mailgun.

Para configurar um ambiente de desenvolvimento Node.js, primeiro crie um novo diretório de projeto e acesse-o executando o seguinte 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
                                
                            

As dependências instaladas incluem o seguinte:

• Axios: esta é uma biblioteca que permite enviar solicitações e receber respostas de uma API. Você usará o Axios para se comunicar com a API do Mailgun.
• Dotenv: esta é uma biblioteca que carrega variáveis de ambiente no process.env. Você a usará para gerenciar seus detalhes de autenticação com segurança.
• Form-Data: esta é uma biblioteca que cria fluxos legíveis do tipo multipart/form-data. A API do Mailgun aceita dados apenas em multipart/form-data, então você precisa dessa biblioteca para enviar formulários para a API.

Após instalar essas dependências, crie um arquivo index.js e um arquivo .env. No seu arquivo .env, armazene as seguintes variáveis e substitua os valores de placeholder pelos seus valores reais:

                                

                                    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 bloco de código importa as dependências necessárias para fazer solicitações à API do Mailgun. Além dos pacotes instalados anteriormente, as importações incluem o módulo fs do Node.js, necessário para criar um fluxo legível para o arquivo contendo sua lista de e-mails.
Agora que seu ambiente de desenvolvimento está pronto, você pode validar endereços de e-mail em uma lista de e-mails.

Como mencionado nos pré-requisitos, para usar o serviço de validação de e-mail em massa com o Mailgun, você precisa ter uma conta paga.

Para criar um trabalho de validação com a API do Mailgun, você precisa fazer uma solicitação POST para https://api.mailgun.net/v4/address/validate/bulk/${listId}, onde listId é qualquer valor arbitrário que você atribuir ao trabalho de validação.

Este endpoint aceita um formulário com um arquivo CSV contendo os endereços de e-mail que você deseja validar. O cabeçalho da coluna para e-mails do arquivo CSV precisa ser email ou email_address, e o formato deve ser CSV bruto ou gzip. Você pode incluir um número ilimitado de endereços de e-mail no arquivo; no entanto, o tamanho do arquivo não pode exceder 25 MB.

A chave do formulário para o arquivo CSV deve ser file, e o valor deve ser um fluxo legível para o caminho do seu arquivo CSV.

Você pode adicionar o bloco de código abaixo ao seu arquivo index.js para implementar uma função e criar um trabalho de validação em massa:

                                

                                    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 uma lista de e-mails leva tempo; para obter os resultados da validação, você precisa fazer uma solicitação à API com o id do seu trabalho de validação.

Para buscar os resultados de um trabalho de validação, você precisa fazer uma solicitação GET para https://api.mailgun.net/v4/address/validate/bulk/${listId}, onde o listId é o id que você atribuiu ao trabalho de validação.

Adicione o bloco de código a seguir ao seu arquivo index.js para implementar uma função e buscar os resultados da sua validação:

                                

                                    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: um carimbo de data/hora de quando o trabalho foi concluído (1728170695).
• download_url: links para baixar os resultados nos formatos CSV e JSON.
• Quantity: o número total de e-mails processados (10).
• Status: o status do trabalho de validação (uploaded).
• Result: o resultado da validação de e-mail:
• catch_all: nenhum endereço é de domínios catch-all.
  • deliverable: três endereços são válidos e podem ser entregues.
  • do_not_send: nenhum endereço foi sinalizado como “não enviar”.
  • undeliverable: um endereço é inválido ou não pode ser entregue.
  • unknown: seis endereços não puderam ser verificados.
• Risk: um detalhamento dos endereços de e-mail por risco:
  • high: um endereço é de alto risco e provavelmente não pode ser entregue ou é problemático.
  • low: três endereços são considerados de baixo risco e seguros para uso.
  • medium: nenhum endereço é de médio risco e pode exigir cautela.
  • unknown: seis endereços não puderam ser classificados.

Ao usar a API do Mailgun para validação de e-mail em massa, você pode encontrar alguns erros comuns. Aqui está um detalhamento desses erros e dicas de como solucioná-los:

• List already exists: este erro de código de status 409 indica que já existe um trabalho de validação com o mesmo listId que você está tentando criar. Você pode corrigir esse erro alterando o listId e tentando fazer a solicitação novamente.
• List CSV file missing: este erro de código de status 400 indica que a API não conseguiu encontrar o arquivo CSV na sua solicitação porque você está usando a chave de arquivo incorreta. Certifique-se de que a sua chave de arquivo esteja definida como file, depois tente novamente.
• CSV File must contain the key email or email_address: este erro de código de status 400 indica que o seu arquivo CSV não possui um cabeçalho de coluna email ou email_address. Você pode corrigir esse erro editando o seu arquivo CSV para conter um desses cabeçalhos.
• CSV file is malformed: este erro de código de status 400 indica que o seu arquivo está em um formato não compatível. Certifique-se de que o arquivo contendo seus e-mails esteja no formato CSV ou gzip.
• unauthorized: este erro de código de status 401 indica um problema com suas credenciais de autenticação. Você pode corrigir isso garantindo que suas chaves de API sejam válidas.

Para garantir que os seus trabalhos de validação em massa funcionem como esperado, aqui estão algumas práticas recomendadas que você pode seguir:

• Respect API limits: certifique-se de respeitar os limites impostos pela API do Mailgun para garantir que todas as suas solicitações sejam processadas. Por exemplo, os arquivos CSV não podem exceder 25 MB; arquivos maiores que isso dispararão uma resposta 400. Além disso, o número máximo de trabalhos de validação que podem ser executados em paralelo é cinco. Ultrapassar esse limite resultará em uma resposta 400.
• Use batching to avoid API limits: se você estiver validando um grande conjunto de dados de e-mails, divida-os em lotes para gerenciar o tamanho do arquivo, mas fique de olho nos limites de processamento paralelo.
• Check for specific status codes: erros diferentes requerem estratégias de tratamento diferentes. Por exemplo, um 400 Bad Request provavelmente indica um problema com o formato da solicitação; não tente novamente. Em vez disso, registre o erro e corrija a solicitação. Um 500 Internal Server Error indica um problema do lado do servidor e você pode tentar novamente após um período de espera.

Neste tutorial, você explorou como verificar e-mails usando Node.js e a API do Mailgun. Você aprendeu a criar listas de e-mails, adicionar membros a elas e validar os endereços de e-mail em massa.

A validação de e-mail em massa regular pode melhorar significativamente suas taxas de entregabilidade de e-mail, manter uma lista de e-mails limpa e eficaz, garantir que suas mensagens cheguem aos destinatários e ajudar você a manter uma boa reputação do remetente.

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