Build on Cold Leads
Cold Leads is a cold-outreach CRM you can drive from code. Verify e-mail addresses before you send, push leads from any form or system, move contacts along the funnel, and give your AI agent the same tools over MCP. Plain JSON, one header for auth, an OpenAPI 3.1 spec to generate clients from.
- OpenAPI 3.1
- ·x-api-key auth
- ·120 requests a minute per key
- ·Hosted MCP server
- ·MIT-licensed SDK on GitHub
curl -X POST https://coldleads.app/api/v1/verify \
-H "x-api-key: $COLDLEADS_API_KEY" \
-d '{"email":"jane@example.com"}'{
"email": "jane@example.com",
"status": "valid",
"score": 75,
"reasons": ["smtp_unreachable"],
"mx": "mx.example.com",
"catch_all": null,
"disposable": false,
"role": false
}Illustrative response. The reason codes tell you whether the mailbox itself was checked.
120/min
requests per key, one auth header
14
MCP tools for Claude, ChatGPT and Cursor
5 days
free trial with API access on Business
Pick the surface that fits
REST API
Verify one address or a list (bulk jobs), look up contacts already in your own CRM, read your credit balance. OpenAPI 3.1 spec for code generation and for agents that import tools from a spec.
OpenAPI 3.1 specLead and stage hooks
A website key (lk_…) turns any form into a lead source and can start an auto-campaign after a delay you choose. The stage hook marks a contact as customer when your billing or CRM system closes the deal.
Hosted MCP server
https://coldleads.app/api/mcp gives Claude, ChatGPT, Cursor and other MCP clients 14 tools: import and update contacts, verify addresses, write templates, draft campaigns and launch them after you approve, read replies. OAuth or a secret key.
Cold Leads for AI agentsNode.js SDK and stdio MCP
Typed client for Node 20 or newer and a local MCP server for Claude Desktop, Cursor and VS Code. Open source, MIT licence, installed straight from GitHub.
github.com/anttka4cz/coldleads-node-sdkFrom sign-up to first call in minutes
Sign up
Create an account with Google or an e-mail link. Start the 5-day free trial on the Business plan to try the API with 25 credits (card required, cancel any time before the trial ends).
Create a key
Settings → API. A secret key (sk_…) for your server, a website key (lk_…) for forms on your site. Secret keys are stored hashed, shown once, and can be paused, rotated or deleted.
Make a call
Send the key in the x-api-key header and call any endpoint below. Errors are JSON with a short code such as rate_limited, no_credits or bad_input.
# 1. Verify an address (1 credit)
curl -X POST https://coldleads.app/api/v1/verify \
-H "x-api-key: $COLDLEADS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com"}'
# 2. Capture a lead from any form (website key lk_…, safe to ship in HTML)
curl -X POST "https://coldleads.app/api/hooks/lead?key=$COLDLEADS_SITE_KEY" \
-d email=jane@example.com -d name="Jane Doe"
# 3. Move a contact along the funnel when the deal closes
curl -X POST https://coldleads.app/api/hooks/stage \
-H "x-api-key: $COLDLEADS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","stage":"customer"}'
# Node.js SDK and MCP server (installed from GitHub)
npm install --allow-git=root github:anttka4cz/coldleads-node-sdk
npx -y --allow-git=root github:anttka4cz/mcp-server-coldleadsReplace the environment variables with your keys. The addresses are illustrative.
A verification answer carries a status (valid, risky or invalid), a score, reason codes, the MX host and a catch_all flag. The reason codes tell you whether the mailbox itself was checked.
Why developers stay
Plain JSON over HTTPS, one auth header, errors with short codes — no SDK required to start.
Every key has its own rate limit and usage counter, and can be paused or rotated without touching the others.
The same engine runs your own campaigns: addresses verified as invalid are never sent to, and campaigns go out from your own Gmail, Microsoft 365 or SMTP mailbox.
AI agents work with approval: they prepare a campaign draft and launch it only after a human confirms the template and audience.
An agent can even start without a key: POST /api/agent/provision returns a payment link for the human owner and a claim token.
Pricing
Website keys work on every plan. The secret-key API (verification, finder, contact search, stage hook) and MCP come with Business: $99/month including 10,000 credits a month. Extra credits cost $5 per 1 000.
Try it first: the 5-day free trial on Business includes the API within trial limits (25 credits). New customers who subscribe within 24 hours of signing up get 30% off the first payment instead of the trial — the two can’t be combined.
Limits
- 120 requests a minute per key.
- 5 parallel bulk jobs, up to 5 000 addresses per job.
- 1 credit per verified address or finder call; results are cached for 30 days and a repeated check still costs a credit.
- Website keys (lk_…) can only create contacts, with a daily cap per key.
What it is not
Recipes
Use Cold Leads from Cursor, Claude Desktop and Windsurf over MCP
Connect Cold Leads MCP or Node SDK to import and manage contacts, read chats, prepare campaigns, launch approved outreach and capture website leads.
Bulk e-mail verification in n8n with Google Sheets
An importable n8n workflow: read a Google Sheet, send up to 5,000 addresses to a Cold Leads bulk job, poll it, route rows by status and write results back.
Verify leads in Make.com before they reach an Instantly campaign
A Make.com scenario that checks each new lead with the Cold Leads API and adds only valid addresses to an Instantly campaign via the Instantly API v2.
Verify a 50,000-row CSV with Python, asyncio and httpx
A complete asyncio + httpx script for the Cold Leads bulk API: jobs of 5,000, five at a time, polling, 429 and 402 handling, resumable CSV output.
Moving e-mail verification from Hunter or Apollo to Cold Leads
Map Hunter's Email Verifier and Email Finder to the Cold Leads API field by field, see what Apollo data has no equivalent, and check Cold Leads costs.
Agent-initiated, human-approved subscriptions
An AI agent without a key asks for a Cold Leads Business subscription, the human owner approves and pays on Stripe, and the agent collects the API key once.
Developer FAQ
Do I need a card to try the API?
Yes. The 5-day free trial needs a card and you can cancel before it ends; nothing is charged during the trial. There is no free plan.
Which plan includes the API?
Business ($99/month, 10,000 credits). Website keys for forms work on every plan. During a Business trial the API works within the trial limits.
Can I generate a client from a spec?
Yes, /api/v1/openapi.json is an OpenAPI 3.1 document. The two hooks are plain HTTP calls described on this page.
Is there an SDK?
A typed Node.js SDK (Node 20 or newer) and an MCP server for local clients, both MIT-licensed on GitHub. Other languages can use the HTTP API directly.
Can an AI agent sign up by itself?
An agent can call POST /api/agent/provision with the owner’s e-mail. It gets a Stripe payment link for the human owner and a claim token; after the owner pays, the agent receives its key once.
What happens when I run out of credits?
Calls return a 402 no_credits error with your remaining balance. Credits renew monthly, and extra packs cost $5 per 1 000.
Ready to build?
Create an account, grab a key and make your first call in a few minutes.
Get your API key