Verifica los correos de los formularios de HubSpot en tiempo real

Un formulario de HubSpot es una máquina de captación de contactos: cada envío crea o actualiza un registro de contacto, establece propiedades y puede inscribir a ese contacto en un flujo de trabajo. Lo que no hará es decirte si la dirección que alguien escribió es realmente real. El campo de correo de HubSpot ejecuta una comprobación de formato —confirma que hay una @ y un dominio—, pero no puede ver que el buzón está muerto, que es desechable o que es una errata de gmail.com. Esta guía muestra dos formas prácticas de verificar los correos de los formularios de HubSpot con Qualisend: en tiempo real, con un flujo de trabajo de Operations Hub que hace un POST de cada nueva dirección a la API de Qualisend, y de forma masiva, exportando los contactos a un CSV. Ninguna necesita un conector nativo —todavía no existe uno—, solo las acciones de flujo de trabajo integradas de HubSpot o su botón de exportación.

La respuesta corta#

Elige la ruta que se ajuste a cuándo necesitas la respuesta:

• Tiempo real — inscribe a los nuevos remitentes de formularios en un flujo de trabajo. Una acción de código personalizado o de webhook llama a la API de Qualisend con el correo, y una rama escribe el veredicto en una propiedad del contacto, para luego derivar o suprimir el registro según el status devuelto.
• Masivo — exporta tus contactos a CSV, pásalos por la verificación masiva de Qualisend y suprime los no entregables antes de tu próximo envío.

Por qué el campo de formulario de HubSpot no puede confirmar un buzón#

El campo email de HubSpot valida el formato: comprueba que la cadena parece una dirección antes de dejar que el formulario se envíe. Esa es la misma clase de comprobación que hace una expresión regular, y falla por las mismas razones: el formato no es entregabilidad. jane@gmial.com supera la comprobación de formato. También lo hace throwaway@mailinator.com, y también una dirección de aspecto real en un dominio que cerró el año pasado.

Ninguna de esas se detecta hasta que envías, y para entonces una dirección muerta es un rebote duro que erosiona tu tasa de rebote y tu reputación como remitente. La verificación real añade las capas que HubSpot no puede: una consulta DNS/MX y un sondeo SMTP del buzón, además de marcadores para direcciones desechables, de rol y catch-all. Si esta cadena de procesos es nueva para ti, qué comprueba realmente la verificación de correo es la introducción.

Dos formas de verificar los correos de los formularios de HubSpot#

Primero, la restricción importante: un formulario estándar de HubSpot no puede bloquear un correo incorrecto a mitad del envío. No hay ninguna manera compatible de llamar a una API externa entre el clic en "Enviar" y la creación del registro, así que la verificación en tiempo real ocurre justo después del envío, dentro de un flujo de trabajo, no como una barrera en línea. Eso condiciona ambas rutas de abajo.

Ruta 1: en tiempo real con un flujo de trabajo de Operations Hub#

Crea un flujo de trabajo basado en contactos y establece el desencadenante de inscripción en "Envío de formulario", acotado al formulario que te interesa. Cada nuevo remitente fluye ahora hacia el flujo de trabajo, donde haces la llamada de verificación y actúas sobre el resultado.

Hay dos maneras de hacer esa llamada: elige la que encaje con tu portal y tu stack.

Opción A — una acción de código personalizado (autónoma). Si estás en Operations Hub Professional o Enterprise, una acción de código personalizado ejecuta Node.js (o Python) directamente dentro del flujo de trabajo. Añade el email del contacto inscrito como propiedad de entrada, guarda tu clave como un secreto llamado QUALISEND_API_KEY y llama a Qualisend desde la acción:

// 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,
    },
  });
};

La acción expone email_status, email_score, email_smtp y qualisend_job_id como salidas. Cuando email_smtp es cached o skipped, el veredicto ya es definitivo. Cuando es pending, la comprobación del buzón sigue en curso y email_status es solo el veredicto local instantáneo (normalmente unknown), así que no derives todavía según él: ramifica según email_smtp, añade un Retraso breve y después una segunda acción de código personalizado que lea el trabajo terminado, con 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" } });
};

En ambas ramas, añade después de la última acción un paso de Copiar valor de propiedad que escriba email_status en una propiedad de contacto personalizada, y luego usa una rama if/then para derivar según ese valor, que es la razón entera por la que ejecutaste la comprobación.

Opción B — una acción de webhook hacia tu propia función. ¿Prefieres mantener la lógica en tu propia base de código, o no estás en un nivel con código personalizado? Añade una acción de webhook que haga un POST a una pequeña función serverless que tú controlas. La función extrae el correo, llama a Qualisend y escribe el veredicto final de vuelta en el contacto con la API del CRM de HubSpot (cuando smtp vuelve como pending, lee ese veredicto de GET /jobs/{job_id} en cuanto termina el trabajo). Es la misma forma del lado del servidor que el patrón de verificar en el registro: la clave de la API nunca sale del servidor, y tú actúas sobre el resultado. El código del endpoint del tutorial de Node.js o del tutorial de Python encaja casi tal cual; solo el análisis del payload es específico de HubSpot.

En cualquier caso, la solicitud subyacente es la misma, y los marcadores de posición son tuyos para rellenarlos desde la documentación para desarrolladores:

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

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

Una dirección entregable vuelve así: un status, un score de 0 a 100, un reason y un 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 }
  }
}

Aquí smtp es cached, así que el veredicto ya es definitivo. Cuando es pending, reason sigue siendo null y los valores definitivos de status, score y reason llegan de la consulta del trabajo.

Dos reglas mantienen esto robusto. Usa una clave dedicada creada solo para este flujo de trabajo (el alcance verify por defecto cubre tanto la comprobación como la consulta del trabajo), para que si alguna vez se filtra de un registro puedas revocarla sin romper nada más. Y falla en abierto: si Qualisend agota el tiempo de espera o se alcanza el límite del plan, trata la dirección como unknown y conserva el contacto en lugar de descartar un lead real por un fallo transitorio, que es exactamente lo que hacen las ramas catch y !res.ok de arriba.

Aguas abajo, el veredicto no es más que una rama. Establece una propiedad personalizada "Estado del correo" a partir de la salida, y luego deja que tu flujo de trabajo decida: un contacto deliverable continúa en la secuencia de maduración; a uno undeliverable o disposable se le retiene el seguimiento, se le marca para revisión o se le fija como no comercial para excluirlo de las listas y los envíos activos. El flujo de trabajo es la fontanería; la derivación es tuya.

Ruta 2: verificar de forma masiva una exportación CSV#

Si ya tienes miles de contactos, o prefieres limpiar según un calendario en lugar de ejecutar comprobaciones por cada envío, hazlo por lotes; y esta ruta no necesita ningún flujo de trabajo, así que también funciona por debajo de los niveles de Operations Hub. En HubSpot, abre Contactos, elige una lista o un filtro y Exporta a CSV. Obtendrás una fila por contacto con el correo en su propia columna.

Luego:

1. Sube el CSV a la verificación masiva de Qualisend y deja que ejecute la cadena completa —MX, SMTP y los marcadores de desechable/rol/catch-all— sobre cada fila.
2. Descarga el archivo anotado. Cada dirección vuelve con un status, un reason y un score de 0 a 100.
3. Suprime las no entregables de vuelta en HubSpot: importa los resultados para establecer tu propiedad "Estado del correo" y luego excluye de tus listas activas y envíos de marketing todo lo que no sea entregable.

Lo masivo es la herramienta adecuada para una acumulación, pero es limpieza, no prevención: una dirección que capturas aquí normalmente ya lleva tiempo sentada en tu base de datos. Combina una pasada masiva periódica con el flujo de trabajo en tiempo real para que las nuevas direcciones incorrectas se marquen en el momento en que llegan.

Actuar sobre el veredicto#

Sea cual sea la ruta que devuelva el resultado, la forma es la misma: un status, un reason, un score y las sub-flags. Asocia cada uno a una acción:

Si estás sopesando el enfoque de flujo de trabajo de HubSpot frente a llamar a la API directamente desde tu propio backend, se aplica la misma disyuntiva que con cualquier pegamento: los flujos de trabajo ganan en rapidez de puesta en marcha, una integración directa gana en coste y control a escala. El mismo patrón de webhook también impulsa las guías hermanas de Zapier y Typeform si parte de tu captación vive fuera de HubSpot.

¿Listo para conectarlo todo? Consigue una clave con alcance limitado y el formato exacto de la solicitud en la documentación para desarrolladores, comprueba una sola dirección en el verificador de correo gratuito, o empieza con los 100 créditos gratis de cada plan para probar el flujo de trabajo de principio a fin antes de activarlo.