Verifique e-mails de formulários HubSpot em tempo real

Um formulário HubSpot é uma máquina de captura de contatos: cada envio cria ou atualiza um registro de contato, define propriedades e pode inscrever esse contato em um fluxo de trabalho. O que ele não faz é dizer se o endereço que alguém digitou é de fato real. O campo de e-mail do HubSpot roda uma checagem de formato — confirma que existe um @ e um domínio — mas não consegue enxergar que a caixa de correio está morta, é descartável ou é um erro de digitação de gmail.com. Este guia mostra duas formas práticas de verificar e-mails de formulários HubSpot com a Qualisend: em tempo real, com um fluxo de trabalho do Operations Hub que faz um POST de cada novo endereço para a API da Qualisend, e em massa, exportando contatos para um CSV. Nenhuma delas precisa de um conector nativo — ainda não existe um — apenas das ações de fluxo de trabalho integradas do HubSpot ou do seu botão de exportação.

A resposta curta#

Escolha o caminho que combina com o momento em que você precisa da resposta:

• Tempo real — inscreva quem envia o formulário em um fluxo de trabalho. Uma ação de código personalizado ou webhook chama a API da Qualisend com o e-mail, e uma ramificação grava o veredito em uma propriedade de contato, depois encaminha ou suprime o registro com base no status retornado.
• Em massa — exporte seus contatos para CSV, passe-os pela verificação em massa da Qualisend e suprima os não entregáveis antes do seu próximo envio.

Por que o campo de formulário do HubSpot não consegue confirmar uma caixa de correio#

O campo email do HubSpot valida o formato — ele verifica se a string parece um endereço antes de deixar o formulário ser enviado. Essa é a mesma classe de checagem que uma regex faz, e ela falha pelas mesmas razões: formato não é entregabilidade. jane@gmial.com passa na checagem de formato. throwaway@mailinator.com também, e o mesmo vale para um endereço de aparência real em um domínio que foi desativado no ano passado.

Nenhum deles é capturado até você enviar — e, a essa altura, um endereço morto vira um hard bounce que corrói a sua taxa de bounce e a reputação do remetente. A verificação de verdade adiciona as camadas que o HubSpot não tem: uma consulta de DNS/MX e uma sondagem SMTP da caixa de correio, além de sinalizações para endereços descartáveis, de função (role) e catch-all. Se essa pipeline for novidade para você, o que a verificação de e-mail realmente checa é o primer.

Duas formas de verificar e-mails de formulários HubSpot#

A restrição importante primeiro: um formulário HubSpot padrão não consegue bloquear um e-mail ruim durante o envio. Não há uma maneira suportada de chamar uma API externa entre o clique em "Enviar" e a criação do registro, então a verificação em tempo real acontece logo após o envio, dentro de um fluxo de trabalho — não como um portão inline. Isso molda os dois caminhos abaixo.

Caminho 1: tempo real com um fluxo de trabalho do Operations Hub#

Crie um fluxo de trabalho baseado em contatos e defina o gatilho de inscrição como "Envio de formulário", restrito ao formulário que interessa a você. Cada novo remetente agora entra no fluxo de trabalho, onde você faz a chamada de verificação e age sobre o resultado.

Há duas formas de fazer essa chamada — escolha a que combina com o seu portal e a sua stack.

Opção A — uma ação de código personalizado (autossuficiente). Se você está no Operations Hub Professional ou Enterprise, uma ação de código personalizado roda Node.js (ou Python) direto dentro do fluxo de trabalho. Adicione o email do contato inscrito como uma propriedade de entrada, armazene sua chave como um segredo chamado QUALISEND_API_KEY e chame a Qualisend a partir da ação:

// HubSpot custom-code action (Node.js) — input property: email, secret: QUALISEND_API_KEY
const QUALISEND_ENDPOINT = "https://app.qualisend.com/api/v1/verify"; // confirm the path in /developers

exports.main = async (event, callback) => {
  const email = event.inputFields.email;

  // Fail open — never block a real lead on a transient API error.
  const failOpen = () => callback({ outputFields: { email_status: "unknown" } });

  let res;
  try {
    res = await fetch(QUALISEND_ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.QUALISEND_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(10000),
    });
  } catch {
    return failOpen(); // timeout or network error
  }
  if (!res.ok) return failOpen(); // 402 out of credits, 429 rate limited, 5xx

  const { job_id, result } = await res.json();
  callback({
    outputFields: {
      email_status: result.status, // deliverable / risky / undeliverable / unknown
      email_score: result.score,
      email_smtp: result.smtp, // pending / cached / skipped
      qualisend_job_id: job_id,
    },
  });
};

A ação expõe email_status, email_score, email_smtp e qualisend_job_id como saídas. Quando email_smtp é cached ou skipped, o veredito já é final. Quando é pending, a checagem da caixa de correio ainda está em andamento e email_status é apenas o veredito local instantâneo (geralmente unknown), então não encaminhe com base nele ainda: ramifique por email_smtp, adicione um Atraso curto e depois uma segunda ação de código personalizado que lê o job concluído, com qualisend_job_id como entrada:

// Second custom-code action, after the Delay: input qualisend_job_id, secret: QUALISEND_API_KEY
exports.main = async (event, callback) => {
  const jobId = event.inputFields.qualisend_job_id;

  try {
    const res = await fetch(`https://app.qualisend.com/api/v1/jobs/${jobId}?include=results`, {
      headers: { Authorization: `Bearer ${process.env.QUALISEND_API_KEY}` },
      signal: AbortSignal.timeout(10000),
    });
    const job = res.ok ? await res.json() : null;
    const row = job?.status === "completed" ? job.results?.[0] : null;
    if (row) {
      return callback({ outputFields: { email_status: row.status, email_score: row.score } });
    }
  } catch {
    // timeout or network error: fall through and fail open
  }

  // Still running, or the API didn't answer: keep it unknown and re-check later.
  callback({ outputFields: { email_status: "unknown" } });
};

Nas duas ramificações, siga a última ação com uma etapa de Copiar valor de propriedade que grava email_status em uma propriedade de contato personalizada e, então, use uma ramificação if/then para encaminhar com base nela: a razão inteira pela qual você rodou a checagem.

Opção B — uma ação de webhook para a sua própria função. Prefere manter a lógica na sua própria base de código, ou não está em um nível com código personalizado? Adicione uma ação de webhook que faz um POST para uma pequena função serverless que você controla. A função extrai o e-mail, chama a Qualisend e grava o veredito final de volta no contato com a API do CRM do HubSpot (quando smtp volta como pending, ela lê esse veredito em GET /jobs/{job_id} assim que o job termina). É o mesmo formato server-side do padrão de verificação no cadastro: a chave da API nunca sai do servidor, e você age sobre o resultado. O código do endpoint no passo a passo em Node.js ou no passo a passo em Python encaixa quase diretamente — apenas a análise do payload é específica do HubSpot.

De qualquer forma, a requisição subjacente é a mesma, e os placeholders são seus para preencher a partir da documentação para desenvolvedores:

POST https://app.qualisend.com/api/v1/verify
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "email": "jane@example.com" }

Um endereço entregável volta assim — um status, um score de 0 a 100, um reason e um conjunto de sub_flags:

{
  "job_id": "6f1d2c3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "result": {
    "status": "deliverable",
    "score": 95,
    "smtp": "cached",
    "reason": "accepted_email",
    "sub_flags": { "disposable": false, "role": false, "free_mail": false, "catch_all": false }
  }
}

Aqui smtp é cached, então o veredito já é final. Quando é pending, reason ainda é null e os valores finais de status, score e reason vêm da consulta ao job.

Duas regras mantêm isso robusto. Use uma chave dedicada criada só para este fluxo de trabalho (o escopo verify padrão cobre tanto a checagem quanto a consulta ao job), de modo que, se ela vazar de um log, você possa revogá-la sem quebrar mais nada. E falhe aberto (fail open): se a Qualisend expirar ou o limite do plano for atingido, trate o endereço como unknown e mantenha o contato, em vez de descartar um lead real por causa de uma falha transitória: é exatamente o que as ramificações catch e !res.ok acima fazem.

Rio abaixo, o veredito é apenas uma ramificação. Defina uma propriedade personalizada "Status do e-mail" a partir da saída, depois deixe seu fluxo de trabalho decidir: um contato deliverable continua na sequência de nutrição; um undeliverable ou disposable tem o follow-up segurado, é sinalizado para revisão ou é definido como não-marketing, para ficar excluído das listas ativas e dos envios. O fluxo de trabalho é o encanamento; o encaminhamento é seu.

Caminho 2: verificar em massa uma exportação em CSV#

Se você já tem milhares de contatos, ou prefere limpar em uma programação a rodar checagens por envio, faça em lotes — e essa rota não precisa de fluxo de trabalho, então funciona também abaixo dos níveis do Operations Hub. No HubSpot, abra Contatos, escolha uma lista ou filtro e Exporte para CSV. Você terá uma linha por contato com o e-mail em sua própria coluna.

Então:

1. Faça o upload do CSV para a verificação em massa da Qualisend e deixe-a rodar a pipeline completa — MX, SMTP e as sinalizações de descartável/função/catch-all — em cada linha.
2. Baixe o arquivo anotado. Cada endereço volta com um status, um reason e um score de 0 a 100.
3. Suprima os não entregáveis de volta no HubSpot: importe os resultados para definir sua propriedade "Status do e-mail", depois exclua tudo o que não for entregável das suas listas ativas e dos envios de marketing.

Em massa é a ferramenta certa para um backlog, mas é limpeza, não prevenção: um endereço que você captura aqui já costuma estar parado na sua base de dados há algum tempo. Combine uma passagem periódica em massa com o fluxo de trabalho em tempo real, para que novos endereços ruins sejam sinalizados no momento em que chegam.

Agindo sobre o veredito#

Qualquer que seja o caminho que retorne o resultado, o formato é o mesmo — um status, um reason, um score e as sub-flags. Mapeie cada um para uma ação:

Se você está pesando a abordagem de fluxo de trabalho do HubSpot contra chamar a API diretamente do seu próprio backend, aplica-se o mesmo trade-off de qualquer cola: os fluxos de trabalho ganham na rapidez para configurar, uma integração direta ganha em custo e controle em escala. O mesmo padrão de webhook também alimenta os guias irmãos para Zapier e Typeform se parte da sua entrada vive fora do HubSpot.

Pronto para conectar tudo? Pegue uma chave com escopo e o formato exato da requisição na documentação para desenvolvedores, teste a sanidade de um único endereço no verificador de e-mail gratuito, ou comece com os 100 créditos gratuitos de todo plano para testar o fluxo de trabalho de ponta a ponta antes de ativá-lo.