Verified email finder

Verified Email Finder#

Return a list of verified business emails by routing the user's input to the right Apify Actor and turning on the leads enrichment + email verification add-ons in a single run. No third-party verifier (Hunter, NeverBounce, Apollo) needed — verification happens inside the same Actor run.

Prerequisites#

(No need to check it upfront)

The skill supports two execution paths. Pick the one that matches your environment — Steps 4 and 5 show commands for both.

MCP path (default in Claude sessions, recommended). If the Apify MCP server is connected, no setup is needed — auth runs through the user's Apify account. Use the call-actor and get-dataset-items MCP tools.

Script path (CLI / scheduled / non-Claude execution). Requires:

• .env file with APIFY_TOKEN
• Node.js 20.6+ (for native --env-file support)

Workflow#

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Collect the six required anchor inputs
- [ ] Step 2: Route to the correct Actor (confirm if ambiguous)
- [ ] Step 3: Build the Actor input (verification always ON)
- [ ] Step 4: Run the Actor and wait
- [ ] Step 5: Apply the result-scope filter, deduplicate, and render

Step 1: Collect the Six Required Anchor Inputs#

Ask all six as one block before any Actor call. Don't bundle Actor-specific optional fields (country code, language, max pages) into this round — surface those as follow-ups.

1. What do you have to start with? — location query / SERP keyword / URL list. This drives the routing decision.
2. The actual input — the location string, the keyword(s), or the URLs themselves.
3. Department filter — one or more of: c_suite, product, engineering_technical, design, education, finance, human_resources, information_technology, legal, marketing, medical_health, operations, sales, consulting. Default is any (leave the array empty), but ask every time.
4. Max contacts per domain / business — passed as maximumLeadsEnrichmentRecords. Default 3, but ask every time.
5. Output format — CSV or JSON. Ask every time.
6. Result scope — which leads to keep in the deliverable. The Actor always runs the same way (verification always on); this only controls post-run filtering. Pick one:
   • verified-only (default) — only leads with emailVerification.result == "ok". Safest for cold email.
   • verified-plus-catchall — ok plus catch_all. Catch-all is often deliverable but unprovable.
   • all-emails — any lead with a non-empty email, regardless of verification.
   • with-phone — any lead with a non-empty phone number, regardless of email status. Use for call campaigns.
   • everything — every lead the Actor returned, even incomplete ones.

Step 2: Route to the Correct Actor#

Inspect anchor #1 and pick the Actor.

All three Actors share the same three add-on fields, so verification behavior is identical across routes.

Decision examples

Ambiguity rule: if anchor #1 is unclear, ask one follow-up before running. Never burn Actor compute on a guessed route.

Mixed deliverables: if the user explicitly asks for two routes in one deliverable, run both Actors and concatenate. The Source column makes the mix clear; dedupe by email across the combined output.

Step 3: Build the Actor Input#

Always set these three fields, regardless of which Actor is selected.

Full per-Actor input parameters and example payloads are in reference/apify-actor-usage.md (opens in a new tab).

URL-list pre-validation: before submitting URLs to vdrmota/contact-info-scraper, parse each one and check it is http/https and parseable. Skipped entries must appear in the output as skipped — invalid URL, never silently dropped.

Step 4: Run the Actor#

Maps and SERP runs with leads enrichment can take several minutes per query. Raise the timeout for large jobs.

MCP path (default in Claude sessions):

Call the call-actor tool:

• actor: one of the three Actor IDs (compass/crawler-google-places, apify/google-search-scraper, vdrmota/contact-info-scraper)
• input: the JSON payload from Step 3
• callOptions: {"timeout": 1800, "memory": 4096} for a generous budget

The tool returns runId and datasetId. If status is still RUNNING, poll with get-actor-run (waitSecs up to 45) until SUCCEEDED. Capture both IDs for the run_metadata.json sidecar.

Script path (CLI / scheduled use):

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_verified-emails.csv \
  --format csv \
  --timeout 900

Use --format json for JSON. The script writes the raw dataset to disk; Step 5 still applies the spurious-match + scope filters on top.

Step 5: Filter, Deduplicate, and Render#

Pull the dataset:

• MCP path: call get-dataset-items with the datasetId from Step 4. Use the fields parameter (e.g., title,searchString,countryCode,city,address,phone,website,leadsEnrichment) and clean: true to keep the response small. For datasets that still exceed the response cap, fetch directly via curl https://api.apify.com/v2/datasets/<id>/items?fields=...&clean=true and pipe through jq.
• Script path: the raw dataset is already on disk in the file from Step 4.

Each record contains business fields plus a leadsEnrichment array (Maps, SERP) or top-level lead fields (URL list). Each lead has a departments array, a companyWebsite, and an emailVerification object with result (ok / invalid / disposable / catch_all / unknown / error) and quality (good / risky / bad).

• Spurious-match filter (mandatory, always on). Apply this first, before any other filter. The lead-enrichment service can return global-fallback leads when no local match exists (real case observed: a single US-zoo CFO whose companyWebsite=zoo.org was attributed to 8 unrelated Polish zoos because the matcher latched onto the zoo substring). Drop any lead whose companyWebsite hostname doesn't equal the source URL's hostname (strip https?://, leading www., anything after /; lowercase). Count drops in run_metadata.json and call them out in the deliverable header if non-zero.

• Filter by result scope (anchor #6). Applied second.

  Scope	Row-keep logic
  verified-only	emailVerification.result == "ok"
  verified-plus-catchall	emailVerification.result in {"ok", "catch_all"}
  all-emails	email is non-empty (any result, including missing verification)
  with-phone	phone (or company phone) is non-empty (regardless of email)
  everything	keep every lead, no filter

• Dedupe: group by lowercased email; keep the first occurrence and merge Source Query or URL if the same email appears from multiple sources. For with-phone rows that have no email, dedupe by lowercased phone instead.

• Empty-result surfacing: if the department filter (anchor #3) produces zero leads for a given domain, include a row for that domain with Email = "" and Email Verification Status = "no leads matched filter". Do not silently drop it. This is separate from the result-scope filter above — empty-domain rows are inserted before scope-filtering and always shown.

Output row schema (16 columns, including Departments) and per-format rendering details are in reference/output-formats.md (opens in a new tab).

Worked Examples#

• Maps: examples/example-maps-input.md (opens in a new tab)
• SERP: examples/example-search-input.md (opens in a new tab)
• URL list: examples/example-url-list-input.md (opens in a new tab)

Quality Rules (always enforce)#

• Guard rail: never submit a run with verifyLeadsEnrichmentEmails: false.
• Provenance & traceability: populate the Source column on every row; carry Apify runId + datasetId in run_metadata.json.
• No fabrication: missing dataset fields stay blank.
• Deliverable header transparency: state the active result scope and the spurious-match drop count; offer to re-render under a different scope.
• Ambiguity confirm: if anchor #1 is unclear, ask before running.

Cost & Pricing#

Email verification is charged only for decisive results (ok / invalid / disposable); catch_all / unknown / error are free. Leads enrichment is charged per successfully extracted lead. Check the Apify console for live rates (they vary by subscription tier and change over time).

Error Handling#

See reference/troubleshooting.md (opens in a new tab).

Supporting file: examples/example-maps-input.md#

Example — Maps route ("dentists in Berlin")#

Anchors#

Optional follow-ups: language=en, maxCrawledPlacesPerSearch=20, scrapePlaceDetailPage=true (so address / phone come back).

Routing: unambiguous → compass/crawler-google-places.

Actor input#

{
  "searchStringsArray": ["dentists"],
  "locationQuery": "Berlin, Germany",
  "maxCrawledPlacesPerSearch": 20,
  "language": "en",
  "scrapePlaceDetailPage": true,
  "maximumLeadsEnrichmentRecords": 3,
  "leadsEnrichmentDepartments": ["marketing", "c_suite"],
  "verifyLeadsEnrichmentEmails": true
}

Run it via the MCP call-actor tool or the script (SKILL.md Step 4). expected_leads = 20 × 3 = 60 — under the 200-lead warning threshold, no confirm needed.

Sample output#

Deliverable header: Scope verified-only, spurious-match drops: 0. Ask to re-render under a wider scope to include catch-all / unknown. A run_metadata.json sidecar is written next to the CSV.

Supporting file: examples/example-search-input.md#

Example — SERP route ("best CRM software")#

Anchors#

Optional follow-ups: countryCode=us, languageCode=en, maxPagesPerQuery=1.

Routing: unambiguous → apify/google-search-scraper.

Actor input#

{
  "queries": "best CRM software",
  "maxPagesPerQuery": 1,
  "countryCode": "us",
  "languageCode": "en",
  "maximumLeadsEnrichmentRecords": 3,
  "leadsEnrichmentDepartments": ["sales"],
  "verifyLeadsEnrichmentEmails": true
}

Run via MCP call-actor or the script (SKILL.md Step 4). expected_leads ≈ 10 × 3 = 30 — well under the warning threshold.

Sample output (truncated to one contact)#

{
  "runMetadata": {
    "runId": "AbCdEfGhIjK",
    "datasetId": "LmNoPqRsTuV",
    "actor": "apify/google-search-scraper",
    "finishedAt": "2026-05-18T13:02:11Z",
    "consoleUrl": "https://console.apify.com/actors/runs/AbCdEfGhIjK"
  },
  "filter": {"scope": "verified-only", "rowKeepLogic": "emailVerification.result == 'ok'"},
  "contacts": [
    {
      "source": "Search",
      "sourceQueryOrUrl": "best CRM software",
      "business": "acme-crm.example",
      "fullName": "Sample Contact 1",
      "jobTitle": "Account Executive",
      "seniority": "manager",
      "email": "contact1@acme-crm.example",
      "emailVerificationStatus": "ok",
      "emailVerificationQuality": "good",
      "linkedin": "http://www.linkedin.com/in/example-user-1",
      "businessWebsite": "https://www.acme-crm.example",
      "dateScraped": "2026-05-18T13:02:11Z"
    }
    /* + 2 more, schema in reference/output-formats.md */
  ]
}

A run_metadata.json sidecar is written next to the JSON output.

Supporting file: examples/example-url-list-input.md#

Example — URL-list route (5 URLs in)#

Anchors#

Optional follow-ups: maxRequestsPerStartUrl=10, maxDepth=2, mergeContacts=true.

Routing: unambiguous → vdrmota/contact-info-scraper.

Pre-validation#

htp://broken-url is skipped (scheme not http/https) → emitted as a skipped — invalid URL row. The other four URLs go to the Actor.

Actor input (only valid URLs)#

{
  "startUrls": [
    {"url": "https://acme-pay.example"},
    {"url": "https://demo-card.example"},
    {"url": "https://sample-bank.example"},
    {"url": "https://example-biz.example"}
  ],
  "maxRequestsPerStartUrl": 10,
  "maxDepth": 2,
  "mergeContacts": true,
  "proxyConfig": {"useApifyProxy": true},
  "maximumLeadsEnrichmentRecords": 2,
  "leadsEnrichmentDepartments": [],
  "verifyLeadsEnrichmentEmails": true
}

Run via MCP call-actor or the script (SKILL.md Step 4). expected_leads = 4 × 2 = 8 — well under the threshold.

Sample output#

Under with-phone scope, every row needs a non-empty phone — verification status is informational, not a gate.

Deliverable header: Scope with-phone, spurious-match drops: 0, 1 URL pre-skipped. Ask to re-render under verified-only to narrow.

Supporting file: reference/apify-actor-usage.md#

Apify Actor Usage#

Exact input parameters per Actor. Every payload includes the three shared add-on fields:

1. Google Maps — compass/crawler-google-places#

Anchor #1 is a location + business type.

Example:

{
  "searchStringsArray": ["dentists"],
  "locationQuery": "Berlin, Germany",
  "maxCrawledPlacesPerSearch": 20,
  "language": "en",
  "scrapePlaceDetailPage": true,
  "maximumLeadsEnrichmentRecords": 3,
  "leadsEnrichmentDepartments": ["marketing", "c_suite"],
  "verifyLeadsEnrichmentEmails": true
}

2. Google Search — apify/google-search-scraper#

Anchor #1 is a keyword.

Example:

{
  "queries": "best CRM software",
  "maxPagesPerQuery": 1,
  "countryCode": "us",
  "languageCode": "en",
  "maximumLeadsEnrichmentRecords": 3,
  "leadsEnrichmentDepartments": ["sales"],
  "verifyLeadsEnrichmentEmails": true
}

3. URL list — vdrmota/contact-info-scraper#

Anchor #1 is a pre-existing URL list.

Example:

{
  "startUrls": [
    {"url": "https://acme-co.example"},
    {"url": "https://demo-co.example"}
  ],
  "maxRequestsPerStartUrl": 10,
  "maxDepth": 2,
  "mergeContacts": true,
  "proxyConfig": {"useApifyProxy": true},
  "maximumLeadsEnrichmentRecords": 3,
  "leadsEnrichmentDepartments": [],
  "verifyLeadsEnrichmentEmails": true
}

Supporting file: reference/output-formats.md#

Output Formats#

One row per contact (subject to anchor #6 scope), in CSV or JSON.

Row schema (16 columns)#

The lead object lives on leadsEnrichment[] for Maps and SERP; URL-list leads sit on the same field inside a per-domain merged record. Field names are the actual keys the Apify lead-enrichment service returns.

Notes:

• departments is a plural array on the lead (not a string field called department). Often empty, but populated for ~30% of leads with values like ["marketing"] or ["c_suite", "finance"]. Join with | for the CSV column.
• Missing fields stay blank — never invent a value.

Filter & dedupe#

1. Spurious-match filter (mandatory, always on). The lead-enrichment service sometimes returns global-fallback leads when no local match exists — e.g., a US-zoo CFO with companyWebsite=zoo.org attributed to 8 unrelated Polish zoos because the matcher latched onto the zoo substring.

   Row-keep logic: extract hostnames (strip https?://, leading www., anything after /; lowercase) from both the source URL and the lead's companyWebsite, and keep only if both non-empty and equal. The source URL is place.website (Maps), the SERP result url (Search), or the original startUrls[].url (URL list). If either hostname is empty, drop the lead.

   Count drops in run_metadata.json under stats.spuriousMatchesDropped and surface in the deliverable header if non-zero.

2. Result-scope filter (anchor #6). Applied after spurious-match.

   Scope	Row-keep logic
   verified-only (default)	emailVerification.result == "ok"
   verified-plus-catchall	emailVerification.result in {"ok", "catch_all"}
   all-emails	email is non-empty (any result, including missing verification)
   with-phone	place phone or companyPhoneNumber is non-empty (regardless of email)
   everything	no filter

3. Dedupe: for scopes that produce email rows, group by email.toLowerCase(). Keep the first occurrence. If the same email comes from multiple sources, concatenate Source Query or URL with |. For with-phone rows that have no email, dedupe by lowercased phone instead.

4. Empty-result rows: if the department filter (anchor #3) produced zero leads for a given domain, include one row for that domain with blank Email and Email Verification Status = "no leads matched filter". These rows are inserted before result-scope filtering and are always shown — they tell the user the filter narrowed too much.

5. Invalid-URL rows (URL-list route only): include one row per pre-skipped URL with Email Verification Status = "skipped — invalid URL". Also always shown.

State both the active result scope and the spurious-match drop count in the deliverable header.

Rendering#

Post-process the raw dataset (from get-dataset-items or the script's output file) the same way regardless of route:

1. Flatten leadsEnrichment so each lead becomes its own row.
2. Apply both filters (spurious-match, then scope).
3. Dedupe.
4. Project to the 16 columns above (CSV) or to a contacts array (JSON).

CSV deliverable — one header row, one row per lead, trailing RUN_METADATA row: RUN_METADATA, runId=..., datasetId=..., actor=..., finishedAt=....

JSON deliverable — envelope:

{
  "runMetadata": {"runId": "...", "datasetId": "...", "actor": "...", "finishedAt": "...", "consoleUrl": "https://console.apify.com/actors/runs/..."},
  "filter": {"scope": "verified-only", "rowKeepLogic": "emailVerification.result == 'ok'"},
  "contacts": [ /* ... */ ]
}

Sidecar — always write run_metadata.json next to the deliverable with the same runMetadata fields plus stats (placesScraped, rawLeads, spuriousMatchesDropped, keptUnderScope). For multi-route deliverables, actor / runId / datasetId become arrays in matching order.

Supporting file: reference/scripts/package.json#

{ "type": "module" }

Supporting file: reference/troubleshooting.md#

Troubleshooting#

Auth / setup#

• APIFY_TOKEN not found (script path only) — Create .env with APIFY_TOKEN=...; get the token from https://console.apify.com/account/integrations. Not needed on the MCP path.
• Actor not found — Confirm the ID is one of compass/crawler-google-places, apify/google-search-scraper, vdrmota/contact-info-scraper. The script converts / to ~ when calling the API; expected.

Run-time#

• Run FAILED — Open the console URL printed by the runner and read the Actor log. Most common cause: malformed input JSON.
• Timeout — Leads enrichment adds 30–90 s per domain on top of the base scrape. Raise the timeout (try 1500–1800 s). If the run is still progressing, the dataset already has partial results — pull by datasetId.
• Run TIMED-OUT from Apify — Lower source breadth (maxCrawledPlacesPerSearch, maxRequestsPerStartUrl, fewer queries).

Empty / weak results#

• No verified rows after filter — Re-render under verified-plus-catchall or all-emails scope. Catch-all SMTP servers can't be proven but often deliver.
• No leads at all — Try in order: bump maximumLeadsEnrichmentRecords; widen leadsEnrichmentDepartments to []; confirm sources have reachable websites (Maps places without a website can't be enriched).
• All leads dropped by spurious-match filter — The enrichment service returned only global-fallback leads. There's no real fix — the source domain has no recognizable LinkedIn footprint. Surface the count and move on.
• Empty SERP queries — Confirm the keyword is non-empty and ≤ 32 words. Strip stray quotes.

URL-list route#

• Blocked domain — Set useBrowser: true in vdrmota/contact-info-scraper input. Raises cost but unblocks most anti-bot sites.
• Invalid URL — Pre-validate in Step 3; emit a skipped — invalid URL row. Never submit a bad URL to the Actor.

Routing ambiguity#

Ask one follow-up. Common patterns: SERP+URL-list pasted together → pick one or both; industry + no source → Maps or SERP?; industry + city without "Maps" → confirm route.

Cost surprises#

Pull the breakdown from the run console. Usual causes: maximumLeadsEnrichmentRecords too high, source breadth uncapped, useBrowser: true left on. Live rates are in the Apify console under the Actor's pricing tab; the 200-lead pre-submit warning rule lives in SKILL.md Step 3.