Cold Leads

npx add-mcp 'https://coldleads.app/api/mcp'

Use cases

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.

Use Cold Leads from Cursor, Claude Desktop and Windsurf over MCP

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.

In this recipe

• What the server offers
• Cursor
• Claude Desktop
• Windsurf (Devin Desktop) and Claude Code
• Prompts that match the real tools
• Check the hosted endpoint from a terminal
• Limits and costs

5 min read

Bulk e-mail verification in n8n with Google Sheets

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.

In this recipe

• What the workflow does
• Prepare the sheet and the credentials
• The workflow
• How the polling loop works
• Routing and write-back
• Limits and costs

5 min read

Verify leads in Make.com before they reach an Instantly campaign

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.

In this recipe

• Before you start
• Build the scenario
• Choose how strict the filter is
• Test both requests from a terminal
• Errors and retries
• Limits and costs

6 min read

Verify a 50,000-row CSV with Python, asyncio and httpx

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.

In this recipe

• How the bulk endpoints behave
• The script
• Run it
• What the script does when something goes wrong
• Limits and costs
• Reading the new columns

5 min read

Moving e-mail verification from Hunter or Apollo to Cold Leads

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.

In this recipe

• What moves and what stays
• Email Verifier to POST /api/v1/verify
• Email Finder to POST /api/v1/find
• A drop-in adapter
• Behaviour differences to plan for
• Limits and costs

5 min read

Agent-initiated, human-approved subscriptions

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.

In this recipe

• The flow at a glance
• Step 1: request a payment link (no key needed)
• Step 2: the owner decides on Stripe
• Step 3: collect the key once
• Optional: a signed callback instead of polling
• Security notes
• Limits and costs

6 min read

How accept-all detection works, and how to read Cold Leads results

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.

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
• A decision table, and a script that applies it
• Limits and costs

6 min read

Verify or find e-mail addresses for new HubSpot and Pipedrive contacts

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.

In this recipe

• How it fits together
• HubSpot: a custom code action in a contact workflow
• Pipedrive: a webhook receiver
• What to write back, and what to do with it
• Limits and costs

3 min read

Cold Leads tools for CrewAI and LangChain agents

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.

In this recipe

• The three tools
• A shared client
• CrewAI
• LangChain
• Descriptions the model can act on
• Limits and costs

4 min read

=VERIFY_EMAIL() and =FIND_EMAIL() in Google Sheets

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.

In this recipe