API de Verificação de E-mail: Escolhendo entre Requisições Únicas, Múltiplas e em Lote

Como escolher a requisição de API de verificação de e-mail correta para cada tarefa e mapear resultados como entregável, não entregável e indeterminado no seu código.

Uma API de verificação de e-mail deve ser chamada em um dos três formatos, escolhidos de acordo com quem está aguardando e quantos endereços você possui. Use uma verificação única (POST /api/v1/check) quando uma pessoa estiver aguardando por um endereço, uma verificação síncrona de múltiplos endereços (POST /api/v1/batch-check, de 1 a 100 endereços, com resultados na ordem de entrada) quando um pequeno grupo chega junto, e uma tarefa de lote assíncrona (POST /api/v1/bulk-tasks, seguida de consulta de status) quando os endereços já estiverem em um arquivo. Independentemente do formato, projete seu código em torno de três resultados em vez de uma sinalização de sim/não: entregável, não entregável e indeterminado, com entradas malformadas sendo tratadas antes da chamada. Cada resultado concluído descreve o endereço apenas no momento da verificação.

O que uma API de verificação de e-mail responde e o que fica sob sua responsabilidade

A maioria das páginas que ranqueiam para este tópico lista recursos e para por aí. A questão da integração é mais específica: o que uma chamada realmente decide e o que sua aplicação ainda deve gerenciar?

A Verificação de entregabilidade de e-mail do EmailCheckPro retorna um resultado concluído como entregável (o endereço podia receber e-mail no momento da verificação) ou não entregável. A Verificação de avatar de e-mail adiciona um sinal de avatar público, mas apenas para endereços Gmail, Yandex e Mail.ru.

Sua aplicação ainda é responsável por três tarefas:

• Triagem de formato. Um endereço completo possui uma parte local, um sinal @ e um domínio. Uma entrada malformada é um erro de formulário, não um veredito de não entregável; portanto, detecte-a antes de gastar uma chamada.
• Um link de confirmação ou seus próprios registros de consentimento cobrem isso.
• Cronometragem. Um resultado pertence ao momento da verificação. Armazene a data ao lado do resultado para que tarefas futuras saibam quão antigo ele é.

Manter esses limites no código, e não apenas na documentação, evita os erros de integração mais comuns descritos abaixo.

Escolhendo o formato de requisição da API de verificação de e-mail

Os três formatos de requisição não são intercambiáveis, e escolher o errado é a causa habitual de formulários lentos ou tarefas de importação frágeis.

Uma maneira rápida de decidir:

1. Há alguém aguardando na tela? Use o endpoint único apenas para o endereço que a pessoa digitou.
2. Os endereços chegam juntos e cabem em 100? Envie uma requisição múltipla. Ela ainda é síncrona: uma chamada única maior, não uma tarefa de lote pequena.
3. A fonte já é um arquivo ou vai muito além de algumas centenas de linhas? Envie uma tarefa de lote e deixe um processo em segundo plano coletar o resultado. Limites de tarefa por produto se aplicam e estão listados na documentação da API.
4. A tarefa precisa de avatares? Filtre a lista primeiro para domínios suportados (Gmail, Yandex e Mail.ru). Um domínio não suportado é rejeitado antes de uma cobrança em tempo real, e em um arquivo de lote de avatar, isso faz a preparação falhar, com a reserva sendo devolvida.

Para algumas centenas de endereços que não estão em um arquivo, tanto várias requisições múltiplas quanto a verificação em tempo real do painel, que processa até 500 endereços, são razoáveis.

Mapeando resultados para a lógica da aplicação

Reduzir resultados a um booleano é onde a maioria das integrações falha. Um pequeno tipo de estado mantém o significado intacto:

Três regras decorrem da documentação:

• Em uma verificação única em tempo real, um endereço indeterminado retorna um código de negócio em vez de um resultado e não é cobrado. Trate esse ramo como seu próprio estado, não como um erro para tentar novamente em um loop rápido.
• Em uma resposta múltipla, cada item informa se um resultado concluído existe. Apenas itens com um resultado contêm entregável ou não entregável; o restante pertence ao ramo de indeterminado ou não concluído.
• Verificações inválidas, falhas e indeterminadas não são cobradas, portanto, tentar novamente mais tarde não custa nada além de tempo. Agende a nova tentativa em vez de repeti-la imediatamente.

Executando tarefas de lote assíncronas sem surpresas

Uma tarefa de lote é uma pequena máquina de estados e pertence a um processo em segundo plano, não a uma requisição web.

1. Prepare o arquivo. Escreva TXT ou CSV com um endereço de e-mail completo por linha. Linhas inválidas e duplicadas são removidas durante a preparação, mas remover lixo óbvio primeiro torna suas próprias contagens mais fáceis de conciliar.
2. Envie e registre. Salve a referência da tarefa retornada por POST /api/v1/bulk-tasks em seu banco de dados, juntamente com o nome do arquivo de origem, o produto usado e o horário de envio. Um processo que trava pode então retomar em vez de reenviar.
3. Consulte com paciência. Consulte GET /api/v1/bulk-tasks/{id} com frequência não superior a 30 segundos. Uma tarefa agendada que verifica uma vez e aguarda se encaixa melhor nisso do que um loop mantendo uma conexão aberta.
4. Baixe prontamente. Uma tarefa bem-sucedida fornece um CSV em um link de download que dura 12 horas. Se o link expirar, consulte a mesma tarefa novamente para obter um novo link em vez de carregar o arquivo uma segunda vez.
5. Mescle por endereço. Como a preparação pode descartar linhas, junte o CSV de resultados de volta aos seus registros por endereço de e-mail, nunca pelo número da linha.

O CSV de entregabilidade associa cada endereço ao seu resultado. O CSV de avatar também informa se um avatar público foi encontrado e fornece um link de avatar, que pode estar vazio mesmo quando um avatar está presente; portanto, trate um link vazio como um valor normal.

Operando a integração no dia a dia

Uma vez que os formatos de requisição e os estados estejam corretos, alguns hábitos operacionais mantêm a integração estável:

• Chaves apenas no lado do servidor. A chave de API consome o saldo da conta, que é compartilhado por verificações web, chamadas REST, tarefas de lote e acesso MCP. Nunca a envie em código de navegador ou celular.
• Verifique no ponto de alteração. Verifique quando um endereço é criado ou editado, então reutilize o resultado armazenado dentro da sua própria janela de re-verificação em vez de chamar a cada visualização de página.
• Falhe aberto no formulário, fechado no pipeline. Se uma verificação for lenta ou não definida durante a inscrição, permita que a pessoa continue com um endereço sinalizado. Em um pipeline de envio, retenha linhas sinalizadas até que tenham um resultado concluído.
• Proteja seu próprio endpoint. Se sua aplicação expõe uma rota de "verificar este endereço", limite a taxa e retorne mensagens consistentes. A orientação de validação de e-mail da OWASP alerta contra permitir que formulários revelem se uma conta existe.
• Forneça o endpoint MCP para clientes de IA. https://emailcheckpro.com/mcp suporta verificações únicas, até 100 endereços por chamada, listagem de produtos e consultas de saldo. O trabalho em lote baseado em arquivo permanece no fluxo de trabalho web ou na API REST.

Os limites de requisição atuais e detalhes de uso são publicados na documentação da API do EmailCheckPro; leia-os lá em vez de codificar suposições.

Uma verificação de formato que corresponde às expectativas da API

A chamada mais barata é aquela que você nunca faz para entradas malformadas. Duas referências ajudam você a escolher uma triagem sensata:

• O padrão HTML WHATWG define o padrão que os navegadores usam para campos type="email". Ele se desvia deliberadamente dos padrões completos de e-mail para permanecer prático, o que o torna uma base razoável para o lado do servidor também.
• RFC 5321 descreve as formas de endereço usadas no transporte de e-mail. Trate-o como uma referência de formato para casos extremos, como partes locais entre aspas, não como uma descrição de como qualquer serviço de verificação funciona.

Na prática: remova espaços em branco, remova pontuação final copiada de documentos, coloque o domínio em minúsculas, mantenha a parte local como inserida e rejeite apenas entradas que claramente carecem de uma parte local, um @ ou um domínio. Padrões excessivamente rígidos que rejeitam sinais de mais ou domínios de nível superior longos afastam usuários reais e devem ser evitados.

FAQ

Quando as equipes devem mudar de chamadas de múltiplos endereços para uma tarefa de lote?

Mude quando os endereços já residirem em um arquivo ou quando uma tarefa precisar de muitas chamadas múltiplas consecutivas apenas para processar uma lista. Requisições múltiplas atendem a grupos de até 100 que chegam juntos e precisam de respostas na mesma resposta. Tarefas de lote atendem a exportações preparadas que podem esperar, porque o resultado chega mais tarde como um CSV e o processo só precisa consultar o status a cada 30 segundos ou menos.

Como uma aplicação deve armazenar resultados da API de verificação de e-mail?

Mantenha o endereço como inserido, o produto usado, o resultado em palavras simples, a data da verificação e a origem do endereço. Esse registro permite que o suporte explique uma decisão, permite que tarefas de re-verificação escolham os resultados mais antigos primeiro e mantém linhas indeterminadas ou não concluídas separadas das não entregáveis. Evite armazenar payloads de resposta brutos como o único registro, pois outros sistemas dependeriam do formato da API.

Um resultado entregável pode substituir um e-mail de confirmação?

Não. Um resultado entregável informa se o endereço podia receber e-mail no momento da verificação, e a verificação em si não envia nada. Um link de confirmação responde a uma pergunta diferente: se a pessoa que inseriu o endereço o controla e concorda em receber mensagens. Muitos fluxos de inscrição usam a verificação para detectar endereços inativos antes do envio, e então contam com a confirmação para consentimento e propriedade.

Qual é a maneira mais segura de tentar novamente verificações que não foram concluídas?

Coloque-as em uma fila com um atraso em vez de tentar novamente na requisição que falhou. Verificações indeterminadas, falhas e inválidas não são cobradas, mas novas tentativas imediatas raramente alteram o resultado e podem tornar seu próprio serviço lento. Uma nova tentativa agendada, com um limite de tentativas e uma nota da data de cada tentativa, mantém o registro honesto e permite que os revisores vejam quais endereços ainda não têm um resultado concluído.

Saiba Mais

Escolha as informações do produto que se encaixam no próximo passo do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →