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.
HubSpot es la respuesta por defecto a «¿qué CRM?», pero un equipo de una a diez personas necesita sobre todo recoger las consultas de su web, enviar mensajes de prospección personales y responder a las contestaciones, y los planes de pago de HubSpot se cobran por usuario, con cuotas de incorporación en las ediciones superiores.
Compare ambos en lo que un equipo pequeño hace cada día: captar consultas, enviar prospección desde su propio buzón, leer las respuestas y mantener un embudo. Cold Leads tiene un precio fijo por cuenta con esas piezas incluidas; HubSpot es una plataforma mucho más grande que añade secuencias, automatización de marketing e informes a medida que se sube de edición.
Qué obtiene: Una visión clara de en qué destaca cada herramienta, los modelos de precios uno al lado del otro y una forma de usar Cold Leads junto a HubSpot si mantiene ambos.
Lemlist y Cold Leads envían correo en frío, pero resuelven problemas distintos: Lemlist es una plataforma de sales engagement para la prospección multicanal que se sincroniza con un CRM, mientras que Cold Leads es el propio CRM, con consultas web, campañas y respuestas en un mismo lugar.
Compárelos según el trabajo que necesita hacer. Si necesita pasos en LinkedIn, llamadas, una base de datos de leads integrada y calentamiento, Lemlist está hecho para eso. Si necesita captar consultas, lanzar campañas personales desde su propio buzón y trabajar cada respuesta en un CRM, lo está Cold Leads.
Qué obtiene: Una comparación de canales, datos, precios y funciones de CRM, con una configuración para equipos que usan Lemlist para la prospección y Cold Leads para las entradas.
Crear un contacto desde cualquier herramienta (JSON)
curl -X POST https://coldleads.app/api/hooks/lead \
-H "Content-Type: application/json" \
-H "x-api-key: lk_your_website_key" \
-d '{
"email": "jane@example.com",
"name": "Jane Example",
"company": "Example Ltd",
"message": "Asked for a demo on the pricing page",
"tag": "demo-request",
"stage": "lead"
Las consultas de un formulario de contacto suelen acabar en el buzón de alguien, se responden tarde o nunca y no se convierten en un embudo visible. La mayoría de los CRM pueden guardarlas, pero los detalles que deciden si un lead recibe respuesta son fáciles de pasar por alto al comparar herramientas.
Evalúe cada CRM con una lista breve: ¿acepta el formulario que ya tiene?, ¿frena a los bots sin captcha?, ¿separa las consultas de los contactos en frío?, ¿reúne la conversación en un solo lugar?, ¿le dice qué responder hoy? Después, configúrelo en menos de una hora.
Qué obtiene: Una lista que puede aplicar a cualquier CRM y una configuración de consultas que funciona en Cold Leads: formulario, etiquetas, fase, campaña de respuesta automática opcional y la cola «Hoy».
Formulario de contacto con fetch que conserva su propio mensaje de éxito
Su sitio ya tiene un formulario de contacto, pero los envíos van a un buzón o a la base de datos de un plugin, no al lugar donde hace el seguimiento. Rehacer el formulario dentro de un CRM cambiaría su diseño.
Mantenga el formulario y envíe sus campos al endpoint de leads de Cold Leads con una clave de sitio web pública: directamente desde el HTML, con el complemento Webhooks de WPForms, con unas líneas de PHP para Contact Form 7 o como acción de formulario personalizada en Webflow.
Qué obtiene: Cada envío se convierte en un contacto de Cold Leads con nombre, empresa, teléfono, mensaje, etiquetas y fase, y el visitante llega a su página de agradecimiento.
Los creadores de formularios guardan las respuestas en sus propios paneles. Usted quiere que cada respuesta se convierta en un contacto del CRM al que pueda responder, pero Typeform y Tally envían sus webhooks en su propio formato anidado, y Google Forms no tiene webhooks.
Use la vía que entrega campos planos al endpoint de leads de Cold Leads: un breve activador de Apps Script para Google Forms, y un escenario de Make o un Zap para Typeform y Tally que asigne las respuestas a email, name, company y message.
Qué obtiene: Cada nueva respuesta del formulario se convierte en un contacto de Cold Leads con el estado de consentimiento inquiry, sus etiquetas y la fase que haya elegido.
Apps Script vinculado al formulario
const COLDLEADS_KEY = "lk_your_website_key";
// Form question title → Cold Leads field
const FIELDS = { "Work e-mail": "email", "Name": "name", "Company": "company", "What do you need?": "message" };
function sendToColdLeads(e) {
const lead = { tag: "google-forms" };
// If the form collects e-mail addresses automatically, use that address.
const respondent = e.response.getRespondentEmail();
if (respondent) lead.email = respondent;
for (const item of e.response.getItemResponses()) {
Los leads llegan por muchas herramientas: widgets de chat, páginas de reserva, pagos de tiendas online, creadores de formularios. Cold Leads no tiene una app en los directorios de Zapier o Make, así que no hay una acción lista para elegir.
Use el paso HTTP genérico que tienen ambas plataformas. Una petición al endpoint de leads con una clave de sitio web crea o actualiza un contacto; en el plan Business, una segunda petición al hook de fase pasa un contacto a customer cuando, por ejemplo, llega un pago.
Qué obtiene: Un Zap o un escenario de Make que convierte cualquier activador en un contacto de Cold Leads con etiquetas y fase, y que opcionalmente actualiza la fase más tarde.
Switching between an AI chat and a CRM means copying names, addresses and replies back and forth, and an assistant without access to your data guesses instead of checking.
Add the hosted Cold Leads MCP server (https://coldleads.app/api/mcp) to ChatGPT or Claude and sign in with your Cold Leads account. The assistant can then read your follow-up queue, verify addresses, look up a lead's history, import contacts, and prepare templates and campaign drafts in your workspace. Sending a message or launching a campaign needs your explicit approval.
Qué obtiene: A chat that works on your own Cold Leads workspace: answers based on real contacts and conversations, drafts you approve before anything is sent, and an audit log of every call.
Claude Code
claude mcp add --transport http coldleads https://coldleads.app/api/mcp
# then, inside Claude Code: /mcp → coldleads → Authenticate