Working recipes for developers and automation builders. Each post has a concrete config, workflow or script for the Cold Leads API and states the limits and credit costs that apply. The API needs a secret key from the Business plan.
Addresses, IDs and results in the examples are illustrative. example.com is reserved for documentation, so a real check of these addresses returns invalid.
Developers who use AI assistants in Cursor, Claude Desktop or Windsurf7 min read
Copying addresses between an assistant, a CRM and a verification tool is slow and error-prone, and an assistant asked for contacts will happily make some up.
Connect the Cold Leads MCP server once. An assistant can work with contacts already in your workspace, import structured rows from a user-provided file, read synced conversations, maintain templates and campaign drafts, and set up website lead forms. Sending remains behind explicit user confirmation and Cold Leads' consent, unsubscribe, DNC, content and account safeguards.
What you get: An assistant that works with your own contact data, inbox and outreach drafts through MCP or the Node SDK, while keeping each website enquiry and outreach consent status distinct.
Calling a verification API once per row is slow and runs into rate limits, while a bulk API needs a job, a polling loop and a reliable way to map results back to the right rows.
One workflow takes up to 5,000 rows that have no result yet, sends their unique addresses as a single Cold Leads bulk job, polls the job every 5 seconds, fetches the results, routes each row by status and writes status, score, reason and a next step into the sheet. Run it again for the next 5,000.
What you get: Four filled columns per row (verify_status, verify_score, verify_reason, next_step) and a workflow you can run again until the whole sheet is done.
Addresses that were never checked go straight into a sending campaign. The invalid ones bounce, and bounces count against the mailboxes that send the campaign.
Put a Cold Leads check between the trigger and Instantly: one HTTP request per lead, a filter that lets only valid results through, and a second HTTP request that adds the lead to your campaign with the Instantly API v2.
What you get: A running Make scenario: new lead, Cold Leads verification, filter, lead added to the Instantly campaign. Leads that fail the filter stop there or go to a review sheet.
Cold Leads module, Body content
{
"email": "{{map the e-mail field of the trigger here}}",
"timeout_ms": 10000
}
Checking one address per request is slow and runs into the rate limit. A naive bulk loop can open more jobs than the account allows, pay twice after a crash, or quietly drop rows whose results never came back.
Normalise and de-duplicate the column, send bulk jobs of up to 5,000 addresses, keep at most five open, poll every job to the end, wait out rate limits, stop cleanly when credits run out, and save the job ids so that a second run resumes instead of paying again.
What you get: Your CSV with three new columns (verify_status, verify_score, verify_reason) and a small .jobs.json file that makes the run resumable.
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.
Verification code is full of vendor-specific parameters and status values. Swapping the endpoint without mapping them quietly changes which addresses a pipeline sends to.
Map every parameter and response field to its Cold Leads counterpart, keep what Cold Leads does not replace (people data, domain search) where it is, and use a small adapter so existing code keeps its shape.
What you get: A field-by-field mapping, a Python adapter that returns Hunter-style fields from Cold Leads, and a Cold Leads cost table for 1,000, 10,000 and 50,000 verifications a month.
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
An agent that needs e-mail verification should never hold a card or subscribe on its own. Sending the human off to sign up, pick a plan and copy a key breaks the task, and pasting keys into chats leaks them.
The agent calls one endpoint without a key and receives a Stripe Checkout link for its owner plus a secret claim token. The owner reviews the plan and decides. After payment, the agent collects the API key exactly once with the claim token, by polling or after a signed callback.
What you get: A working secret API key for the owner's new Business account, delivered to the agent once, and an e-mail to the owner with a link to open the Cold Leads web app.
Some mail servers accept mail for any address at their domain, so a mailbox check cannot tell a real person from a made-up name. Other servers answer only temporarily, or cannot be reached at all, and a bare valid label can hide the fact that the mailbox was never checked.
Understand the SMTP dialogue a verifier runs and what each reply means, then read the status, score and reason codes Cold Leads returns, including the cases in which the mailbox probe did not run.
What you get: A decision table that maps every Cold Leads reason code to an action, and a script that applies it to one address.
Two SMTP sessions (illustration)
# 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
In this recipe
The SMTP dialogue behind a mailbox check
Reply codes and what they allow you to conclude
The accept-all probe, greylisting and other limits
What Cold Leads returns, and when the probe did not run
Contacts arrive from forms, imports and manual entry with typos, dead domains or no address at all, and nobody checks them until a campaign bounces.
Check each contact when it is created: a custom code action in a HubSpot workflow, or a small webhook receiver for Pipedrive. A contact with an e-mail is verified; a contact without one but with a name and a company website gets a suggested address that is clearly marked as a guess.
What you get: Contact properties in HubSpot or person fields in Pipedrive that show the Cold Leads status, score and reason, or a suggested address with its method and confidence.
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 },
In this recipe
How it fits together
HubSpot: a custom code action in a contact workflow
An agent asked for contact details will guess, and a guessed address looks exactly like a real one. Without a verification tool, neither the agent nor the person reading its output can tell the difference.
Give the agent three narrow tools backed by the Cold Leads API: search the user's own CRM, verify an address, and guess an address from a name and a domain with an honest method label. Errors come back as data, so the agent can react instead of crashing.
What you get: A shared API client, tool classes for CrewAI and for LangChain, and a minimal crew and agent that use them.
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 "
Exporting a sheet to a verification tool and pasting the results back is tedious. A naive custom function calls the API again, and spends a credit again, every time Sheets runs the formula again.
Two custom functions call the Cold Leads API with UrlFetchApp, read the key from the script properties and keep each answer in the script cache for up to six hours, so running the same formula again does not spend another credit for the same input.
What you get: Three result cells per row: status, score and reason from =VERIFY_EMAIL, or address, method and confidence from =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 is the default answer to "which CRM?", but a team of one to ten people mostly needs to catch website enquiries, send personal outreach and answer replies, and HubSpot's paid tiers are priced per seat with onboarding fees on the higher editions.
Compare the two on what a small team actually does every day: capturing enquiries, sending outreach from its own mailbox, reading replies and keeping a pipeline. Cold Leads is a flat price per account with those pieces built in; HubSpot is a much larger platform that adds sequences, marketing automation and reporting as you move up its editions.
What you get: A clear picture of where each tool is stronger, the pricing models side by side, and a way to run Cold Leads next to HubSpot if you keep both.
Lemlist and Cold Leads both send cold e-mail, but they solve different problems: Lemlist is a sales engagement platform for multichannel prospecting that syncs to a CRM, while Cold Leads is the CRM itself, with website enquiries, campaigns and replies in one place.
Compare them on the job you need done. If you need LinkedIn steps, calls, a built-in lead database and warm-up, Lemlist is built for that. If you need to capture enquiries, run personal campaigns from your own mailbox and work every reply in one CRM, Cold Leads is.
What you get: A side-by-side view of channels, data, pricing and CRM features, with a setup for teams that use Lemlist for prospecting and Cold Leads for the inbound side.
Create a contact from any tool (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"
Enquiries from a contact form usually end up in someone's mailbox, get answered late or not at all, and never become a pipeline you can see. Most CRMs can store them, but the details that decide whether a lead is answered are easy to miss when you compare tools.
Judge each CRM against a short checklist: does it accept the form you already have, does it stop bots without a captcha, does it keep enquiries apart from cold contacts, does it put the conversation in one place and does it tell you what to answer today. Then set it up in under an hour.
What you get: A checklist you can use on any CRM, and a working enquiry setup in Cold Leads: form, tags, stage, optional automatic reply campaign and the Today queue.
Contact form with a fetch call that keeps your own success message
Your site already has a contact form, but its submissions go to an inbox or a plugin's database, not to the place where you follow up. Rebuilding the form inside a CRM would change your design.
Keep the form and send its fields to Cold Leads' lead endpoint with a public website key: directly from the HTML, with the WPForms Webhooks addon, with a few lines of PHP for Contact Form 7, or as a custom form action in Webflow.
What you get: Each submission becomes a Cold Leads contact with name, company, phone, message, tags and stage, and the visitor lands on your thank-you page.
Form builders keep responses in their own dashboards. You want each response to become a CRM contact you can answer, but Typeform and Tally send their webhooks in their own nested format, and Google Forms has no webhooks at all.
Use the route that delivers flat fields to Cold Leads' lead endpoint: a short Apps Script trigger for Google Forms, and a Make scenario or Zap for Typeform and Tally that maps the answers to email, name, company and message.
What you get: Every new form response becomes a Cold Leads contact with consent status inquiry, your tags and the stage you chose.
Apps Script bound to the form
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()) {
Leads arrive in many tools: chat widgets, booking pages, e-commerce checkouts, form builders. Cold Leads has no app in the Zapier or Make directories, so there is no ready-made action to pick.
Use the generic HTTP step both platforms have. One request to the lead endpoint with a website key creates or updates a contact; on the Business plan a second request to the stage hook moves a contact to customer when, for example, a payment arrives.
What you get: A Zap or Make scenario that turns any trigger into a Cold Leads contact with tags and stage, and optionally updates the stage later.
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.
What you get: 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