# Cold Leads — full reference for AI agents

> A CRM and sales execution layer for humans and AI agents: persistent lead memory, e-mail verification, outreach from the user's own mailbox, reply tracking and classification, follow-ups and an audit log. AI agents find and research prospects elsewhere; Cold Leads manages what happens after.

Generated from the Cold Leads source code; it changes together with the product. Short version: https://coldleads.app/llms.txt · capability manifest: https://coldleads.app/.well-known/agent-capabilities.json · agents.txt: https://coldleads.app/.well-known/agents.txt (JSON: https://coldleads.app/.well-known/agents.json) · MCP server card: https://coldleads.app/.well-known/mcp/server-card.json · OpenAPI: https://coldleads.app/api/v1/openapi.json

## What Cold Leads provides and what it does not
Provides: crm, lead_management, email_verification, email_outreach, campaign_management, conversation_tracking, reply_classification, follow_up_management, sales_memory, website_lead_capture, agent_audit_log, human_approval.
Does not provide: lead_database, contact_enrichment, web_scraping, linkedin_automation, outgoing_webhooks. The user (or the agent) supplies the prospects; Cold Leads stores, verifies, contacts and remembers them.

## Connect
- MCP (hosted): https://coldleads.app/api/mcp — Streamable HTTP, stateless JSON-RPC over POST. Auth: OAuth 2.1 (ChatGPT and other OAuth clients) or Authorization: Bearer sk_… (Business plan).
- MCP (local stdio for Claude Desktop, Cursor, VS Code): npx -y --allow-git=root github:anttka4cz/mcp-server-coldleads with COLDLEADS_API_KEY — https://github.com/anttka4cz/mcp-server-coldleads
- REST API: https://coldleads.app/api/v1 with the header x-api-key: sk_… (Business plan). OpenAPI 3.1: https://coldleads.app/api/v1/openapi.json
- Node.js SDK (Node 20+): npm install --allow-git=root github:anttka4cz/coldleads-node-sdk — https://github.com/anttka4cz/coldleads-node-sdk
- Website lead capture (every plan): POST https://coldleads.app/api/hooks/lead with a website key lk_…
- No key yet: POST https://coldleads.app/api/agent/provision {"owner_email","agent_id"} returns a Stripe payment link for the human owner (Business plan) and a claim_token.

## The sales loop
1. research (agent): Find and research the prospect with your own tools (web, LinkedIn, your data). Cold Leads has no lead database.
2. store (coldleads): import_contacts — save the prospect to the CRM (deduplicated, do-not-contact refused).
3. verify (coldleads): verify_email — syntax, disposable, role, MX; SMTP mailbox check only when reachable. 1 credit.
4. understand (coldleads): get_lead_context — history, last reply class, do-not-contact, next action, last messages.
5. personalize (agent): Write the message with your own model, using the context.
6. prepare (coldleads): save_template + create_campaign_draft for many recipients, or a single message for one contact.
7. approve (human): Show the user the recipient(s), final text and recipient estimate; get explicit approval.
8. send (coldleads): send_contact_message (confirm_send=true) or launch_campaign (confirm_launch=true) — from the user's connected mailbox (Gmail, Microsoft 365, SMTP or own domain) or, if none is connected, from the shared Cold Leads sender with the user's reply-to address (campaigns from it are capped at 100 e-mails a day); campaigns run with daily limits and pacing.
9. learn (coldleads): Replies are synced and classified automatically (positive, neutral, negative, unsubscribe, auto); unsubscribe opts the contact out. Read them with get_conversation or get_lead_context.
10. follow_up (coldleads): get_sales_next_actions — who waits for an answer and whose follow-up is due; schedule_follow_up records the next step; update_contact moves the stage.

## Reply classes
- positive: Wants to continue: interested, asks for details, price, a call or a meeting. Suggested next action: reply.
- neutral: Question, needs clarification, later, or forwarded to a colleague. Suggested next action: reply.
- negative: Declined or not interested; stop outreach unless they write again. Suggested next action: close.
- unsubscribe: Asked to stop e-mails; the contact was opted out automatically. Suggested next action: none.
- auto: Out-of-office or automatic reply; follow up after they return. Suggested next action: follow_up_later.

## Safety rules
- Sending is never implicit: send_contact_message needs confirm_send=true and launch_campaign needs confirm_launch=true, set only after the user approved the exact message or campaign.
- Opted-out, bounced and do-not-contact addresses are refused for single messages and excluded from campaigns; a reply classified as unsubscribe opts the contact out automatically.
- Campaigns send with a per-campaign daily limit, the workspace daily limit and human-like pacing; plan caps limit recipients per campaign; the shared Cold Leads sender (used when no mailbox is connected) is capped at 100 campaign e-mails a day per account.
- Every outgoing template, campaign and message is screened by the acceptable-use policy; repeated violations suspend the account.
- Imports deduplicate by e-mail and refuse addresses on the global do-not-contact list; importing and verifying never send e-mail.
- Secret keys are stored hashed, can be paused or rotated, and are rate-limited to 120 requests a minute; website keys (lk_) can only create contacts.
- Every API and MCP call is recorded in an audit log without arguments or personal data (get_agent_activity, GET /api/v1/activity).

## Limits and pricing
- 120 requests a minute per key; 5 parallel bulk verification jobs, up to 5000 addresses each; 1 credit per address or finder call; cached results also cost a credit.
- API and MCP: Business plan, $99/month with 10,000 credits a month; extra credits $5 per 1 000. 5-day free trial with a card (the API works within trial limits on a Business trial). No free plan.

## Errors
REST errors are JSON {"error": "<code>", ...}: missing_api_key, bad_api_key, publishable_key_not_allowed, api_not_in_plan, account_suspended, rate_limited (429, Retry-After: 60), no_credits (402), bad_body, lead_required, not_found, invalid_arguments. MCP tool errors return isError with {"status":"error","error":"<code>","message":"…"}; other codes include confirmation_required, do_not_contact, content_blocked, sender_not_configured, aup_required, campaign_limit, template_limit, empty_audience, invalid_state.

## MCP tool reference (18 tools)
### search_leads — Search leads by company domain
Side effect: read · cost: free · requires approval: no · REST: GET /api/v1/leads
Look up B2B leads already saved in the user's Cold Leads CRM by company domain, optionally narrowed to a role keyword (e.g. sales, ceo, marketing) — use it to answer "who do we already have at example.com?" or to find a decision maker the user has already collected before writing to them. Returns e-mail, name, company, phone, funnel stage, tags, last verification status and a do_not_contact flag. It does NOT search the web or a third-party lead database and does not enrich data: it only covers contacts this workspace imported, captured from its website or added by hand. Free, uses no credits.
Arguments:
    - domain (required): string — Company domain, e.g. example.com. A URL or an e-mail address is reduced to its domain.
    - role: string — Optional keyword such as sales, ceo or marketing, matched against the contact's name, e-mail local part, tags, notes and type.
    - limit: integer — Maximum number of leads to return (1–50, default 10).

### verify_email — Verify an e-mail address
Side effect: read · cost: 1_credit · requires approval: no · REST: POST /api/v1/verify
Email verification for one address before outreach: checks syntax, disposable domains, role accounts (info@, sales@) and MX records, and runs an SMTP mailbox and catch-all check only when Cold Leads can open an SMTP connection to the recipient's mail server — otherwise reasons contains smtp_unreachable (mailbox not checked) and catch_all is null. Use it to clean a prospect list or check a single address before sending; call it once per address. Returns validity (valid, risky or invalid), a score and reason codes; the result is not saved to a CRM contact. Answers within about 5 seconds; costs 1 credit per call.
Arguments:
    - email (required): string — The e-mail address to verify, e.g. anna@example.com.

### list_contacts — List CRM contacts
Side effect: read · cost: free · requires approval: no
List contacts (prospects, leads and customers) in the user's Cold Leads CRM, newest first, optionally filtered by free text (matches e-mail, name or company), funnel stage or tag. Use it to review a list, pick contacts for a message or campaign, or get the contact_id needed by update_contact, get_conversation or send_contact_message. For "who do we have at a company domain" use search_leads instead. Read-only, free.
Arguments:
    - query: string — Free text matched against e-mail, name and company.
    - stage: string — Funnel stage: cold, subscriber, lead, customer or regular.
    - tag: string — Return only contacts whose tags contain this text.
    - limit: integer — Maximum contacts to return (default 25).

### import_contacts — Import contacts
Side effect: write · cost: free · requires approval: no
Add B2B prospects or leads to the user's Cold Leads CRM: up to 100 structured rows per call (e-mail required; name, company, phone, tags, notes, consent optional). Use it when the user pastes or uploads a list — parse CSV/XLSX/text yourself and pass the rows; call repeatedly for longer lists. New contacts start in the cold stage; existing e-mails are skipped (deduplicated) and global do-not-contact addresses are refused. consent defaults to inquiry; set b2b_outreach only when the user confirms a lawful basis for cold outreach. Importing never sends e-mail and does not verify addresses (use verify_email). Cold Leads does not supply contacts — the user must provide them.
Arguments:
    - contacts (required): array

### update_contact — Update a CRM contact
Side effect: write · cost: free · requires approval: no
Update one contact in the user's Cold Leads CRM: name, company, phone, funnel stage (cold, subscriber, lead, customer, regular), tags, notes, or opt them out. Use it to record a reply outcome, move a lead through the pipeline or tag a segment for a campaign. Opting out is one-way through this tool and blocks all future e-mail to the contact. Free.
Arguments:
    - contact_id (required): string — Contact id from list_contacts.
    - name: string
    - company: string
    - phone: string
    - stage: string — cold, subscriber, lead, customer or regular.
    - tags: string — Comma-separated tags; replaces the current tags.
    - notes: string
    - opted_out: boolean — Only true is accepted: permanently stops e-mail to this contact.

### get_conversation — Read a contact conversation
Side effect: read · cost: free · requires approval: no
Read the recent e-mail conversation with one CRM contact (incoming and outgoing messages, with reply intent labels: positive, neutral, negative, unsubscribe or auto). Use it before replying or following up so the next message fits the thread. Incoming mail appears only when the user's mailbox is connected and synced in Cold Leads. Read-only, free.
Arguments:
    - contact_id (required): string — Contact id from list_contacts.
    - limit: integer — Most recent messages to return (default 50).

### send_contact_message — Send a contact email
Side effect: external_side_effect · cost: free · requires approval: yes
Send one personal e-mail (a reply or follow-up) to one existing CRM contact from the user's connected mailbox; the workspace signature is appended and the message is threaded into the contact's conversation. Before calling, show the user the recipient, subject and final text and get explicit approval, then pass confirm_send=true — every call really sends. Refused for opted-out, bounced or do-not-contact contacts, blocked content, or when no outbound mailbox is connected. For many recipients use a campaign (create_campaign_draft) instead.
Arguments:
    - contact_id (required): string — Recipient contact id.
    - subject: string — Optional; defaults to a reply to the latest thread subject.
    - message (required): string — Plain-text body approved by the user.
    - confirm_send (required): boolean = true — Must be true, set only after the user approved this exact message.

### list_templates — List email templates
Side effect: read · cost: free · requires approval: no
List the user's Cold Leads e-mail templates with subject and body. Use it to reuse or review copy, or to get a template_id for create_campaign_draft. Read-only, free.
Arguments:
    - limit: integer — Maximum items to return (default 50).

### save_template — Create or update an email template
Side effect: write · cost: free · requires approval: no
Create a new e-mail template or update an existing one (pass template_id) in the user's Cold Leads workspace, for later use in campaigns. Placeholders such as {name} and {company} are filled per recipient. Use it after drafting outreach copy with the user. Content is screened by the Cold Leads acceptable-use policy and plan template limits apply. Never sends e-mail.
Arguments:
    - template_id: string — Pass to update an existing template; omit to create one.
    - name (required): string
    - subject (required): string
    - body (required): string — Plain-text body; {name} and {company} are replaced per recipient.
    - locale: string — Language code such as en, cs, de (default en).

### list_campaigns — List campaigns
Side effect: read · cost: free · requires approval: no
List the user's Cold Leads e-mail campaigns with status (draft, sending or done), audience filters and current eligible-recipient counts. Use it to check progress or find a draft's campaign_id. Read-only, free.
Arguments:
    - limit: integer — Maximum items to return (default 50).

### create_campaign_draft — Create a campaign draft
Side effect: write · cost: free · requires approval: no
Prepare a cold e-mail or follow-up campaign as a draft: pick a template and target contacts by funnel stage, tag and consent. Returns the draft and a recipient estimate (opted-out, bounced and verified-invalid contacts, and contacts who already received this template, are excluded) so the user can review who would receive it. Nothing is sent until launch_campaign is called with the user's confirmation. Plan campaign limits apply.
Arguments:
    - name (required): string
    - template_id (required): string — Template id from list_templates or save_template.
    - stage: string — Target funnel stage: cold, subscriber, lead, customer or regular.
    - tag: string — Target contacts carrying this tag.
    - consent: string [inquiry, b2b_outreach] — Target only contacts with this consent basis.

### launch_campaign — Launch a campaign
Side effect: external_side_effect · cost: free · requires approval: yes
Start sending a reviewed draft campaign. Call only after the user has seen the template and recipient estimate and explicitly approved the launch; pass confirm_launch=true. Delivery runs in the background from the user's mailbox with daily limits and pacing; content policy, plan caps, unsubscribe, do-not-contact and opt-out rules are enforced, and the call fails if no eligible recipients remain.
Arguments:
    - campaign_id (required): string — Draft campaign id from create_campaign_draft or list_campaigns.
    - confirm_launch (required): boolean = true — Must be true, set only after the user approved the launch.

### get_lead_context — Get everything known about a lead
Side effect: read · cost: free · requires approval: no · REST: GET /api/v1/leads/context
One call before deciding what to do with a lead: identity (name, company, stage, tags, notes, source), contactability (do_not_contact with reasons, consent, last e-mail verification, safe_to_contact), relationship (messages sent and received, campaign templates received, last contacted, last reply and its class), the next action (reply, close, follow_up or none, with reason and due date) and the last 5 messages. Pass contact_id or email. Use it instead of chaining list_contacts, get_conversation and search_leads. Reply classes: positive, neutral, negative, unsubscribe, auto. Read-only, free.
Arguments:
    - contact_id: string — Contact id from list_contacts or search results.
    - email: string — Contact e-mail address (alternative to contact_id).

### get_sales_next_actions — What should I do next?
Side effect: read · cost: free · requires approval: no · REST: GET /api/v1/next-actions
The workspace's sales to-do list, the same as the Today queue in the Cold Leads inbox: contacts who replied and have no answer yet (positive replies first; negative ones marked close) and contacts whose follow-up date has arrived (overdue ones marked high priority). Each item has contact_id, action (reply, close or follow_up), priority, reason and due date. A good first call for an agent that continues sales work across sessions. Read-only, free.
Arguments:
    - limit: integer — Maximum actions to return (default 25).

### schedule_follow_up — Schedule a follow-up
Side effect: write · cost: free · requires approval: no · REST: POST /api/v1/follow-ups
Set, move or clear the next action for one contact — the same follow-up date and note the user sees on the contact card and in the inbox Today queue. Pass contact_id or email, plus due_at (ISO 8601) or in_days (0–365, at 09:00 UTC), and an optional short note such as "send pricing"; or clear=true when the follow-up is done. A reply from the contact clears it automatically. Never sends e-mail. Free.
Arguments:
    - contact_id: string — Contact id from list_contacts or search results.
    - email: string — Contact e-mail address (alternative to contact_id).
    - due_at: string — When to follow up, ISO 8601, e.g. 2026-10-14T09:00:00Z (within a year).
    - in_days: integer — Alternative to due_at: days from now (09:00 UTC).
    - note: string — What to do, e.g. send pricing information.
    - clear: boolean = true — Remove the scheduled follow-up.

### get_agent_activity — Get the agent activity log
Side effect: read · cost: free · requires approval: no · REST: GET /api/v1/activity
Audit trail of API and MCP calls made for this workspace, newest first: time, channel (mcp_oauth, mcp_key or api), operation (tool name or endpoint), success, status and error code, duration. Arguments, e-mail addresses and message text are never logged. Kept for 90 days. Use it to check what an agent already did or to debug a failed workflow. Read-only, free.
Arguments:
    - limit: integer — Maximum entries to return (default 50).

### get_workspace_info — Get workspace information
Side effect: read · cost: free · requires approval: no
Get the Cold Leads workspace overview: plan and subscription status, contact/template/campaign counts, sender name, daily sending limit and whether an outbound mailbox is connected. Use it first to understand what the user can do (e.g. whether sending is possible). Never returns credentials, billing identifiers or tokens. Read-only, free.
Arguments:
    (no arguments)

### setup_website_lead_capture — Set up website lead capture
Side effect: external_side_effect · cost: free · requires approval: no
Set up inbound lead capture on the user's website: creates a public, submit-only key restricted to that site and returns an HTML form and a JavaScript snippet that send each enquiry straight into the CRM. Use it when the user wants website visitors or sign-ups to become leads. Submissions arrive as inquiry contacts (not consent for cold outreach). The key is shown only once — give the user the snippet.
Arguments:
    - site (required): string — Website origin the form will run on, e.g. https://example.com.
    - name: string — Optional key label shown in Settings.

## Contact
support@coldleads.app · https://coldleads.app/developers