Snov.io MCP Server

Snov.io

B2B email prospecting + outreach data. Five capability areas, one shared credit pool, one shared bearer-token auth: account balance + plan visibility, email finding (name + domain or whole-domain crawl), email verification, ICP database search (plan-gated), and prospect list management for staging contacts before pushing them into a campaign.

The credit model (read this first)

Every workspace has one shared credit pool that resets monthly. The pool is consumed by finding new contact data, not by searching for it.

• A search that returns "we don't know" or "we know nothing new about this contact" is free.
• A search that returns a previously-unknown email charges 1 credit. Re-searching the same email later is free (cached).
• An email verification charges 0.5 credit per verified address (or 1 credit per not_verified → verified transition, depending on plan).
• Bulk operations charge per result row, not per request — searching a domain that returns 50 emails costs 50 credits if all 50 are new.

Always call get_account_balance before a credit-spending burst. The response carries the balance and the days remaining in the current billing window.

Authentication shape (informational, not actionable)

Snov speaks OAuth2 client_credentials internally. The framework holds the user's client_id + client_secret (Snov dashboard labels them "API User ID" and "API Secret" — same values, just rebranded) and exchanges them for a fresh ~60-minute bearer token on every call. The model never sees raw credentials and there is nothing to refresh manually.

Capability areas

1. Account & balance

• Balance + plan window — current credit balance, billing-window days remaining, whether the workspace is teamwork-enabled.

Use this as the cheapest sanity check that auth is wired correctly: it returns 200 even on Trial accounts and consumes zero credits.

2. Email finding (the main free→paid funnel)

Three strategies, ranked by precision:

• By person + domain — supply firstName, lastName, domain. Returns 0–N candidate emails, each tagged with a emailStatus (unknown, valid, invalid). Highest signal when the person is publicly attached to the company. 1 credit per candidate returned.
• By whole domain — supply domain, optional type=personal|generic|all and limit (max 100 per call). Returns staff inboxes Snov has previously crawled. Cheapest per email, but biased toward larger / older companies that have been crawled. 1 credit per email returned.
• By LinkedIn URL — queue a linkedin.com/in/<slug> URL for asynchronous email discovery. Returns 200 immediately; the resolved email lands on the prospect record once Snov's worker completes. Useful when you have a name → LinkedIn map but no domain.

The single-email lookup (get_prospect_by_email) is read-only against your existing prospect database — it does NOT call out to find a new email. Use it to check whether an address is already enriched in your workspace.

3. Email verification

Two-step async flow:

1. Submit emails — verify_emails posts a list of addresses for verification. Returns immediately with status not_verified for each address (Snov queues the SMTP probe internally).
2. Re-call the same endpoint — calling verify_emails with the same addresses again returns the resolved status (valid, invalid, unknown, accept_all, etc.) once Snov's worker finishes (typically a few seconds).

There is no separate "check status" endpoint — the same verify_emails call is both the submit and the poll. Use it idempotently.

4. ICP database search (API-permission gated)

find_prospects searches Snov's full B2B prospect database with structured filters (countries, locations, job_titles, industries, company_sizes, seniorities, …). The search ITSELF is free; revealing a returned prospect's email costs 1 credit per profile.

Direct curl against a paid Snov key returned HTTP 403 with Sorry, but you dont have permissions for this action. for /v2/prospects/search, while token exchange and get_account_balance succeeded. Surface the upstream error verbatim and do not present the endpoint as available from the stored credential until Snov enables API permission for that account.

5. Lists (the staging surface)

A Snov List is a reusable bucket of prospect records. The canonical pre-outreach flow is:

1. upsert_list(name=...) → returns a numeric listId.
2. Add prospects to it — either one at a time (add_prospect_to_list) or by piping email-finder / domain-search / database-search results into the same list.
3. get_list_prospects(listId) to inspect the staged contents (paginated, max 5000 per page, returned in reverse-chronological order).
4. Push the list into an outreach campaign (Snov's own native sender or via export to another tool).

List shape: {id, name, contacts, isDeleted, creationDate, deletionDate}. Only name is stored on the list itself — there is no description / tags / metadata field at the list level. Group by naming convention (e.g. ICP-cto-saas-eu-q1).

Adding a prospect requires a non-bogus email shape (name@domain.tld) — the call validates format up front but does NOT verify deliverability (that's the verifier's job). Re-adding the same email returns added: false, updated: true rather than failing.

Operational order (do these in this sequence)

1. get_account_balance — confirm credit headroom before a burst.
2. Choose a discovery strategy:
   • Have name + domain → find_emails_by_name.
   • Have domain only → get_domain_emails (paginate with lastId for > 100 results).
   • Have LinkedIn URL → queue_linkedin_url_search, poll the prospect record afterwards.
   • Have an ICP and a Pro+ plan → find_prospects.
3. Stage the discovered contacts into a list (upsert_list then add_prospect_to_list).
4. verify_emails against the staged addresses before sending — bad addresses tank deliverability for the whole sender.
5. Push the verified list into the outreach channel (Snov's native sender, or export to Smartlead / Instantly / Lemlist).

Error envelope

• HTTP 4xx → {"errors": {"code": <int>, "title": <str>, "source": <str>}}. The most common are 404 (endpoint typo or resource gone) and 403 (plan-gated).
• HTTP 200 with {"success": false, "message": "…"} → upstream validation failure (bad email format, missing required field). The framework raises a ToolError with the full body so the model can surface it to the caller.

Date filters

The list creation date is returned as a Snov-flavoured composite ({date, timezone_type, timezone}) rather than ISO 8601. Always read the date sub-field for the wall-clock timestamp.