# Snov.io

> Snov.io is a sales automation and lead generation platform used by 300,000+ companies across
> 180+ countries. It exposes two distinct programmable surfaces: a credit-metered REST API at
> https://api.snov.io for email finding, domain and database search, email verification,
> multichannel campaigns, email warm-up, prospect management and webhooks; and a first-party
> remote Model Context Protocol server at https://mcp.snov.io/mcp exposing 100+ actions for
> prospecting, Sales CRM and LinkedIn outreach.

GENERATED BY API EVANGELIST — this file is NOT published by Snov.io. Snov.io serves no
/llms.txt (https://snov.io/llms.txt returns HTTP 404, probed 2026-08-13). Generated 2026-08-13
from apis.yml and the artifacts in this repository. Source of record for every fact below is
the provider's own documentation at https://snov.io/api.

## Read this first

- The REST API and the MCP server use DIFFERENT credentials and are NOT interchangeable.
  REST: OAuth 2.0 client_credentials -> Bearer token, from https://app.snov.io/account/api.
  MCP: OAuth 2.0 authorization_code + PKCE against https://app.snov.io, scope `mcp`.
- Neither surface is a superset of the other. Campaigns, warm-up, sender accounts and webhooks
  are REST-only. CRM deals/notes/tasks and all LinkedIn write actions are MCP-only.
- Almost every operation costs credits, and the API is capped at 60 requests per minute with
  no rate-limit response headers. Pace at 1 req/s; you get no back-off signal.
- There is NO idempotency mechanism. A retried POST can double-charge credits.

## Authentication

REST token exchange:

    POST https://api.snov.io/v1/oauth/access_token
    grant_type=client_credentials&client_id=<id>&client_secret=<secret>

Returns `access_token` valid for 3600 seconds. Send as `Authorization: Bearer <token>`.
There is no refresh_token grant — re-exchange before expiry.

- Auth profile: [authentication/snov-io-authentication.yml](../authentication/snov-io-authentication.yml)
- Scopes: [scopes/snov-io-scopes.yml](../scopes/snov-io-scopes.yml)
- Docs: https://snov.io/knowledgebase/how-to-use-snov-io-api/

## The async pattern you must implement

Every search, enrichment and verification call is two steps:

1. `POST .../start` returns `{"data":{"task_hash":"<32 hex>"}}`
2. `GET .../result?task_hash=<hash>` returns `status: in_progress` until `status: completed`

Alternative: pass `webhook_url` on the /start call and Snov.io POSTs the completed result to
you instead. No failure terminal state is documented — only `in_progress` and `completed`.

## APIs

### REST — https://api.snov.io
- Email Finder — find emails by name + domain, resolve a company domain from its name.
  `POST /v2/emails-by-domain-by-name/start`, `POST /v2/company-domain-by-name/start`
- Domain Search — crawl a domain for prospects, emails and generic contacts.
  `POST /v2/domain-search/start`, `/prospects/start`, `/domain-emails/start`, `/generic-contacts/start`
- Email Verification — up to 10 addresses per request.
  `POST /v2/email-verification/start` -> `GET /v2/email-verification/result`
- Enrichment — LinkedIn profile enrichment from up to 10 URLs; profile lookup by email.
  `POST /v2/li-profiles-by-urls/start`, `POST /v1/get-profile-by-email`
- Prospects — add to list, fetch by id/email, custom fields, list and create lists.
  `POST /v1/add-prospect-to-list`, `POST /v1/get-prospect-by-id`, `GET /v1/get-user-lists`
- Campaigns — create/read/update/delete campaigns, step content, recipients, do-not-email.
  `GET /v2/campaigns/`, `POST /v2/campaigns/create`, `POST /v2/campaigns/{id}/action`
- Analytics — campaign analytics, progress, recipient activity, sends, opens, clicks, replies.
  `GET /v2/statistics/campaign-analytics`, `GET /v1/get-emails-opened`
- Email Accounts — connect and manage sender mailboxes, check SMTP/IMAP status.
  `GET /v2/sender-accounts/emails`, `GET /v2/sender-accounts/check-sender-status`
- Email Warm-up — create and manage warm-up campaigns and read warm-up statistics.
  `GET /v2/warm-up`, `POST /v2/warm-up`
- CRM Pipeline — read-only pipelines and stages. `GET /v2/pipelines`
- User — account credit balance. `GET /v1/get-balance`
- Webhooks — subscribe to 20 event actions across 8 objects. `GET|POST /v2/webhooks`

Documented but NOT captured in this repository's OpenAPI: the Database Search family
(`/v2/database-search/prospects/start`, `/companies/start`, `/prospects/search-emails/...`).

### MCP — https://mcp.snov.io/mcp
Remote, OAuth-gated, 100+ actions. Groups: prospect search and enrichment; list and folder
management; CRM pipelines, deals, notes, loss reasons and tasks; LinkedIn account setup;
LinkedIn outreach actions. Available on every plan including the free Trial.
Setup: Claude Desktop -> Settings -> Connectors -> Add custom connector -> remote server URL
`https://mcp.snov.io/mcp`.

## Machine-readable artifacts in this repository

- OpenAPI (API Evangelist generations from the HTML reference — Snov.io publishes none):
  [openapi/](../openapi/)
- MCP server profile: [mcp/snov-io-mcp.yml](../mcp/snov-io-mcp.yml)
- MCP <-> REST crosswalk: [mcp/snov-io-tool-crosswalk.yml](../mcp/snov-io-tool-crosswalk.yml)
- Webhook event catalog: [asyncapi/snov-io-webhooks.yml](../asyncapi/snov-io-webhooks.yml)
- Conventions (async, pagination, envelopes, metering):
  [conventions/snov-io-conventions.yml](../conventions/snov-io-conventions.yml)
- Errors: [errors/snov-io-problem-types.yml](../errors/snov-io-problem-types.yml)
- Data model: [data-model/snov-io-data-model.yml](../data-model/snov-io-data-model.yml)
- Rate limits: [rate-limits/snov-io-rate-limits.yml](../rate-limits/snov-io-rate-limits.yml)
- Plans and pricing: [plans/snov-io-plans-pricing.yml](../plans/snov-io-plans-pricing.yml)
- FinOps / credit model: [finops/snov-io-finops.yml](../finops/snov-io-finops.yml)
- Lifecycle and versioning: [lifecycle/snov-io-lifecycle.yml](../lifecycle/snov-io-lifecycle.yml)
- Standards conformance: [conformance/snov-io-conformance.yml](../conformance/snov-io-conformance.yml)
- Client packages: [packages/snov-io-packages.yml](../packages/snov-io-packages.yml)
- Agent Skills: [skills/](../skills/)
- Well-known probe: [well-known/snov-io-well-known.yml](../well-known/snov-io-well-known.yml)

## Provider links

- Website: https://snov.io/
- API reference: https://snov.io/api
- MCP: https://snov.io/mcp
- MCP setup guide: https://snov.io/knowledgebase/how-to-use-snov-io-mcp-with-your-ai-assistant/
- Knowledgebase: https://snov.io/knowledgebase/
- Pricing: https://snov.io/pricing
- Security Center: https://snov.io/security-center
- Release notes: https://snov.io/release-notes
- Official GitHub: https://github.com/devsnovio
- Blog: https://snov.io/blog/

## Known gaps (as of 2026-08-13)

- No provider-published OpenAPI, AsyncAPI or GraphQL schema.
- No first-party SDK in any language. Docs teach raw PHP cURL and Python requests only.
- No /llms.txt, no /.well-known/security.txt, no A2A agent card.
- No API changelog; the product release-notes page renders client-side only.
- No public status page (https://snov.io/status is a 16-byte health check, not a status page).
- No webhook payload signing.
- No published error-code reference; three incompatible error envelopes are in use.
- No documented response for rate-limit breach or credit exhaustion.