Recetas prácticas para desarrolladores y creadores de automatizaciones. Cada publicación incluye una configuración, un flujo o un script concreto para la API de Cold Leads e indica los límites y el coste en créditos. La API requiere una clave secreta del plan Business.
Las direcciones, los identificadores y los resultados de los ejemplos son ilustrativos. example.com está reservado para documentación, así que una comprobación real de estas direcciones devuelve invalid.
Desarrolladores que usan asistentes de IA en Cursor, Claude Desktop o Windsurf7 min de lectura
Copiar direcciones entre un asistente, un CRM y una herramienta de verificación es lento y propenso a errores, y un asistente al que se le piden contactos se inventará algunos sin reparo.
Un asistente conectado puede gestionar sus contactos, importar filas estructuradas, leer conversaciones sincronizadas, preparar plantillas y borradores de campaña y configurar formularios web. El envío exige confirmación expresa del usuario y se somete a las protecciones de consentimiento, bajas, DNC y límites de Cold Leads.
Qué obtiene: Un asistente que trabaja con sus contactos, buzón y borradores de campaña mediante MCP o el SDK de Node.
Llamar a una API de verificación una vez por fila es lento y choca con los límites de peticiones, mientras que una API masiva necesita una tarea, un bucle de sondeo y una forma fiable de devolver cada resultado a su fila.
Un solo flujo toma hasta 5 000 filas que aún no tienen resultado, envía sus direcciones únicas como una sola tarea masiva de Cold Leads, consulta la tarea cada 5 segundos, descarga los resultados, enruta cada fila por estado y escribe en la hoja el estado, la puntuación, el motivo y un siguiente paso. Vuelva a ejecutarlo para las 5 000 siguientes.
Qué obtiene: Cuatro columnas rellenas por fila (verify_status, verify_score, verify_reason, next_step) y un flujo que puede volver a ejecutar hasta completar toda la hoja.
Las direcciones que nunca se comprobaron van directamente a una campaña de envío. Las no válidas rebotan, y los rebotes cuentan en contra de los buzones que envían la campaña.
Ponga una comprobación de Cold Leads entre el disparador e Instantly: una petición HTTP por lead, un filtro que solo deja pasar los resultados válidos y una segunda petición HTTP que añade el lead a su campaña con la API v2 de Instantly.
Qué obtiene: Un escenario de Make en marcha: lead nuevo, verificación con Cold Leads, filtro, lead añadido a la campaña de Instantly. Los leads que no pasan el filtro se quedan ahí o van a una hoja de revisión.
Módulo de Cold Leads, Body content
{
"email": "{{map the e-mail field of the trigger here}}",
"timeout_ms": 10000
}
Comprobar una dirección por petición es lento y choca con el límite de peticiones. Un bucle masivo ingenuo puede abrir más tareas de las que permite la cuenta, pagar dos veces tras un fallo o perder en silencio filas cuyos resultados nunca llegaron.
Normalice la columna y elimine duplicados, envíe tareas masivas de hasta 5 000 direcciones, mantenga como máximo cinco abiertas, consulte cada tarea hasta el final, espere cuando salte el límite de peticiones, deténgase limpiamente cuando se acaben los créditos y guarde los id de las tareas para que una segunda ejecución continúe en lugar de volver a pagar.
Qué obtiene: Su CSV con tres columnas nuevas (verify_status, verify_score, verify_reason) y un pequeño archivo .jobs.json que permite reanudar la ejecución.
verify_csv.py
"""Verify a large CSV with the Cold Leads bulk API (Python 3.9+, httpx).
pip install httpx
export COLDLEADS_API_KEY=sk_...
python verify_csv.py leads.csv leads_verified.csv --column email
Addresses are normalised and de-duplicated, sent in jobs of up to 5,000 with at most
5 jobs open at a time, and every job is polled until it is done. The output is the
input CSV plus verify_status, verify_score and verify_reason. Job ids are saved next
to the output file, so a second run resumes the same jobs instead of paying twice.
El código de verificación está lleno de parámetros y valores de estado propios de cada proveedor. Cambiar el endpoint sin mapearlos altera en silencio a qué direcciones envía un pipeline.
Mapee cada parámetro y campo de respuesta a su equivalente en Cold Leads, deje donde está lo que Cold Leads no sustituye (datos de personas, búsqueda por dominio) y use un pequeño adaptador para que el código existente conserve su forma.
Qué obtiene: Un mapeo campo a campo, un adaptador de Python que devuelve campos al estilo de Hunter a partir de Cold Leads y una tabla de costes de Cold Leads para 1 000, 10 000 y 50 000 verificaciones al mes.
hunter_adapter.py
# pip install httpx
# Drop-in helpers for code written against Hunter's email-verifier and email-finder.
# They call Cold Leads and return Hunter-style fields, plus the raw Cold Leads answer.
import os
import httpx
cold = httpx.Client(
base_url="https://coldleads.app/api/v1",
headers={"x-api-key": os.environ["COLDLEADS_API_KEY"]}, # the key goes in a header, never in the URL
Un agente que necesita verificar correos nunca debería tener una tarjeta ni suscribirse por su cuenta. Mandar a la persona a registrarse, elegir un plan y copiar una clave interrumpe la tarea, y pegar claves en chats hace que se filtren.
El agente llama a un endpoint sin clave y recibe un enlace de Stripe Checkout para su propietario más un token de reclamación secreto. El propietario revisa el plan y decide. Tras el pago, el agente recoge la clave de API exactamente una vez con el token de reclamación, mediante sondeo o tras un callback firmado.
Qué obtiene: Una clave secreta de API operativa para la nueva cuenta Business del propietario, entregada al agente una sola vez, y un correo al propietario con un enlace para abrir la aplicación web de Cold Leads.
Algunos servidores de correo aceptan correo para cualquier dirección de su dominio, así que una comprobación de buzón no puede distinguir a una persona real de un nombre inventado. Otros servidores solo responden de forma temporal, o no se puede conectar con ellos en absoluto, y una simple etiqueta valid puede ocultar que el buzón nunca se comprobó.
Entienda el diálogo SMTP que ejecuta un verificador y qué significa cada respuesta; después lea el estado, la puntuación y los códigos de motivo que devuelve Cold Leads, incluidos los casos en que la comprobación del buzón no se ejecutó.
Qué obtiene: Una tabla de decisión que asigna una acción a cada código de motivo de Cold Leads, y un script que la aplica a una dirección.
Dos sesiones SMTP (ilustración)
# Session 1: is the address accepted?
S: 220 mx1.example.com ESMTP
C: EHLO verifier.example.net
S: 250-mx1.example.com
S: 250 SIZE 52428800
C: MAIL FROM:<check@verifier.example.net>
S: 250 2.1.0 Sender OK
C: RCPT TO:<anna@example.com>
S: 250 2.1.5 Recipient OK <- accepted (a 550 here would mean: rejected)
C: QUIT <- no DATA command: nothing is delivered
En esta receta
El diálogo SMTP detrás de una comprobación de buzón
Los códigos de respuesta y lo que permiten concluir
La prueba de accept-all, el greylisting y otros límites
Qué devuelve Cold Leads y cuándo no se ejecutó la comprobación
Los contactos llegan de formularios, importaciones y altas manuales con erratas, dominios muertos o sin dirección, y nadie los comprueba hasta que una campaña rebota.
Compruebe cada contacto al crearse: una acción de código personalizado en un flujo de trabajo de HubSpot o un pequeño receptor de webhooks para Pipedrive. Un contacto con correo se verifica; un contacto sin correo pero con nombre y web de la empresa recibe una dirección sugerida, claramente marcada como suposición.
Qué obtiene: Propiedades de contacto en HubSpot o campos de persona en Pipedrive que muestran el estado, la puntuación y el motivo de Cold Leads, o una dirección sugerida con su método y su confianza.
Custom code (Node.js)
// HubSpot workflow, Custom code action (Node.js)
// Secret: COLDLEADS_API_KEY (your Cold Leads secret key, sk_...)
// Properties to include in code: email, firstname, lastname, website
// Data outputs (add them in the action): verify_status, verify_reason, suggested_email, find_method (String);
// verify_score, find_confidence (Number); mailbox_checked (Boolean)
const axios = require("axios");
const coldleads = axios.create({
baseURL: "https://coldleads.app/api/v1",
headers: { "x-api-key": process.env.COLDLEADS_API_KEY },
En esta receta
Cómo encaja todo
HubSpot: una acción de código personalizado en un flujo de contactos
Un agente al que se le piden datos de contacto los adivinará, y una dirección adivinada parece exactamente una real. Sin una herramienta de verificación, ni el agente ni la persona que lee su resultado pueden distinguirlas.
Dé al agente tres herramientas acotadas basadas en la API de Cold Leads: buscar en el propio CRM del usuario, verificar una dirección y deducir una dirección a partir de un nombre y un dominio con una etiqueta de método honesta. Los errores vuelven como datos, así que el agente puede reaccionar en lugar de fallar.
Qué obtiene: Un cliente de API compartido, clases de herramientas para CrewAI y para LangChain, y una crew y un agente mínimos que las usan.
coldleads_tools.py
# coldleads_tools.py - shared by the CrewAI and LangChain examples (pip install httpx)
import json
import os
import httpx
VERIFY_DESC = (
"Verify one e-mail address with Cold Leads (costs 1 credit). Returns status valid, risky or invalid, "
"a score from 0 to 100 and reason codes. The last reason says what was checked: ok means a mail server "
"accepted the mailbox, smtp_unreachable means the mailbox itself was not checked, catch_all means the "
Exportar una hoja a una herramienta de verificación y volver a pegar los resultados es tedioso. Una función personalizada ingenua vuelve a llamar a la API, y vuelve a gastar un crédito, cada vez que Sheets ejecuta de nuevo la fórmula.
Dos funciones personalizadas llaman a la API de Cold Leads con UrlFetchApp, leen la clave de las propiedades del script y guardan cada respuesta en la caché del script hasta seis horas, así que volver a ejecutar la misma fórmula no gasta otro crédito con la misma entrada.
Qué obtiene: Tres celdas de resultado por fila: estado, puntuación y motivo con =VERIFY_EMAIL, o dirección, método y confianza con =FIND_EMAIL.
Code.gs
// Cold Leads custom functions for Google Sheets (Extensions → Apps Script, paste into Code.gs).
// Key: Project Settings → Script Properties → Add script property COLDLEADS_API_KEY = sk_...
const COLDLEADS_API = 'https://coldleads.app/api/v1';
const CACHE_SECONDS = 21600; // 6 hours, the longest CacheService keeps an entry
/**
* Verifies an e-mail address with Cold Leads. Fills three cells: status, score, last reason code.
* Costs 1 Cold Leads credit unless the same address was answered from this script's cache.
*
* @param {string} email The address, for example A2.
