Cold Leads for AI agents

When an agent should use Cold Leads

Pick Cold Leads when the user already has contacts (a list, a file, website enquiries) and wants to verify them, reach out by e-mail, follow up and keep track of replies:

• “Import these prospects and check which e-mail addresses are valid” — import_contacts, verify_email.
• “Write a short intro e-mail and send it to everyone tagged expo-2026” — save_template, create_campaign_draft, launch_campaign after approval.
• “Who do we already have at example.com in sales?” — search_leads.
• “Read Jane's reply and answer her” — list_contacts, get_conversation, send_contact_message after approval.
• “Put a contact form on my website that feeds the CRM” — setup_website_lead_capture.

What Cold Leads does not do

Cold Leads has no third-party lead database: it does not find new people, search LinkedIn or the web, or enrich contacts with job titles or company data. The user brings the contacts — their own lists, event exports, website forms. If the task is “find 100 founders in Germany”, use a data provider first, then import the result here to verify it and run the outreach.

MCP endpoint and authentication

Endpoint: https://coldleads.app/api/mcp — Streamable HTTP, stateless, JSON-RPC 2.0 over POST, protocol versions 2024-11-05 to 2025-11-25. Without credentials the server still answers initialize and tools/list, so clients can discover the tools before signing in.

OAuth 2.1 with PKCE and dynamic client registration: ChatGPT and other clients that support MCP authorization sign in with the user's Cold Leads account and ask for consent. Discovery documents are at /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-authorization-server.

Secret API key: send Authorization: Bearer sk_… (or x-api-key) from Settings → API keys. The API and MCP are part of the Business plan ($99/month, 10,000 credits). An agent without any credentials can call POST /api/agent/provision to get a payment link for its human owner.

# Claude Code — remote MCP over HTTP with a secret key
claude mcp add --transport http coldleads https://coldleads.app/api/mcp \
  --header "Authorization: Bearer sk_…"

# Claude Desktop, Cursor, Windsurf, VS Code — local stdio server from GitHub
npx -y --allow-git=root github:anttka4cz/mcp-server-coldleads   # env COLDLEADS_API_KEY=sk_…

• code MCP server for local clients — github.com/anttka4cz/mcp-server-coldleads

Tools

Every tool works only inside the connected user's workspace. Read-only tools are marked as such in the tool annotations.

• Contacts: list_contacts, import_contacts (up to 100 rows per call; the assistant parses CSV/XLSX), update_contact (stage, tags, notes, opt-out), search_leads (contacts already in the CRM at a company domain, optional role keyword).
• E-mail verification: verify_email — syntax, disposable domains, role accounts, MX, and an SMTP mailbox check when Cold Leads can reach the recipient's mail server (otherwise the reason smtp_unreachable). 1 credit per address, about 5 seconds.
• Outreach: list_templates, save_template, list_campaigns, create_campaign_draft (returns a recipient estimate), launch_campaign (confirm_launch=true after the user approves).
• Conversations: get_conversation (mailbox-synced thread with reply labels), send_contact_message (one e-mail, confirm_send=true after the user approves).
• Workspace: get_workspace_info (plan, limits, mailbox status — a good first call), setup_website_lead_capture (public form key and snippet).

Example workflows

Illustrative runs; the tool calls are what an assistant would make. Addresses use the reserved example.com domain.

"Verify these 40 addresses before I send anything."
  → verify_email × 40  (40 credits; for thousands use POST /api/v1/verify/bulk or the web app)
  → update_contact … tags "verified-oct" for the valid ones already in the CRM

"Import the attached CSV of 250 SaaS founders I met at the expo and prepare an intro campaign."
  → import_contacts × 3  (100 + 100 + 50 rows, tags "expo-2026", consent b2b_outreach confirmed by the user)
  → save_template  ("Quick follow-up from the expo", {name} and {company} placeholders)
  → create_campaign_draft  (tag "expo-2026") → shows the recipient estimate
  → user reviews the text and audience → launch_campaign (confirm_launch=true)

"Who do we have at example.com? I want to reach their head of sales."
  → search_leads  (domain "example.com", role "sales")  → existing contacts only

"Answer Jane's reply and move her to lead."
  → list_contacts (query "jane@example.com") → get_conversation → draft shown to the user
  → send_contact_message (confirm_send=true) → update_contact (stage "lead")

Safeguards built into the tools

Sending tools require an explicit confirmation flag that the assistant may set only after the user approved the exact message or campaign. Opted-out, bounced and do-not-contact addresses are never e-mailed, campaign content passes the acceptable-use check, and plan limits, daily sending limits and pacing apply. Website sign-ups are stored as inquiries, not as consent for cold outreach.

Documentation

Machine-readable references and the open-source clients:

• code API reference (JSON) — coldleads.app/api/v1
• code OpenAPI 3.1 — coldleads.app/api/v1/openapi.json
• code llms.txt — coldleads.app/llms.txt
• code Node.js SDK — github.com/anttka4cz/coldleads-node-sdk

FAQ