email-list-cleaner

Email List Cleaner

Overview

This skill turns a list of unknown quality into five files and a report: send_ready.csv (valid addresses only), catch_all.csv, hold_unknown.csv, role_review.csv and removed.csv, plus the suppression rows to add to the sending platform. Every input row ends up in exactly one file, and every removed row carries a reason code.

The mistake it prevents: validating the raw export as-is and sending to everything marked "valid" or "catch-all" in one campaign. Paying to validate duplicates and already-suppressed rows wastes money, and mixing catch-all addresses into the main send is how a list that "passed validation" still bounces at 6% and trips the sequencer's auto-pause. The order of operations here (repair, dedupe, suppress, then validate) is what keeps the bill and the bounce rate low.

When to Use

• "Clean this list before we send." "Verify these 20,000 emails."
• A list more than four weeks past its last validation, or one that has never been validated.
• A bounce spike on a live campaign (pause first, then clean the remaining rows).
• An inherited list: a former employee's export, an event list, an acquired company's CRM.
• A re-launch to a list that was last mailed months ago.

Use a different skill when:

Prerequisites

Authoritative Foundations

Source details and a routing table for this skill's files: references/framework-notes.md.

Workflow

1. Profile the file

Count rows, find the email column (or columns: some exports carry email, email_2, work_email), and record blank emails, cells with more than one address, and the source and last-mailed date. Assign a risk tier:

2. Repair syntax

Apply the rules in references/syntax-repair-and-role-rules.md: trim, strip mailto: and display names (Dana Ruiz <[email protected]>), split multi-address cells into separate rows, remove zero-width characters, fix known consumer-domain typos (gmial.com to gmail.com). Never rewrite a corporate domain. Log every change in fix_applied. Rows that still fail syntax go to removed.csv with reason syntax; they are not sent to the validator.

3. Dedupe

Build email_key: lowercase the full address; for consumer gmail.com and googlemail.com addresses only, also drop dots and any +tag in the local part. Keep one row per key using the survivorship order in references/list-quality-standard.md section 4b. Record how many rows each key collapsed.

4. Suppress before you pay

Match the deduped rows against unsubscribes, hard bounces, complaints, current customers, open opportunities and competitor domains, in that order (exact email first, then domain). Suppressed rows go to removed.csv with the list name as the reason. RFC 2142 network-operations mailboxes (abuse@, postmaster@, hostmaster@, noc@, security@) are removed here too: RFC 2142 routes them to the people who handle abuse reports, not buyers.

5. Flag role and free-provider addresses

Set is_role = true for the local parts listed in the reference file. On a named-contact B2B list, role rows are validated but routed to role_review.csv; on local business and ecommerce lists they stay in the main flow. Set is_free = true for consumer providers; on a B2B list keep them only when the person is a sole proprietor or the business uses that address publicly.

6. Show the count and cost, then validate

Unique addresses to validate x $0.00169 is the cost. Call check_wallet, show the funnel so far and the cost, and wait for a go-ahead before submitting. Then submit:

• A list short enough to fit in one tool argument: MCP validate_emails with the array.
• Larger files: one-column text files, submitted through the CLI or REST, one run per file; split into chunks of a size the user picks only so a failed run is cheap to retry. The runbook is references/batching-and-revalidation-runbook.md.

Poll check_run_status; a typical run finishes in minutes. download_results when SUCCEEDED.

7. Map results and route every row

Read the downloaded header row first; the documented columns are email, email_result, email_quality, subresult, free, plus sc_ enrichment columns such as sc_is_catch_all, sc_mx_provider and sc_mx_security_gateway. Route with references/status-handling-matrix.md:

8. Check the projection and hand off

Hard bounces on send_ready.csv should stay under 2% (Berman; Instantly's default auto-pause is 5% once a campaign has sent 200). Report the invalid rate per source: a source far above the others is stale or mis-mapped and should not be reused. When the list lives in a CRM, write email_status and email_validated_at back to every record and enroll sequences only from a view filtered on valid status validated within four weeks, so the next campaign cannot pull an unchecked row. Write the report from templates/output-template.md, run scripts/check-output.py on it, and set the re-validation dates: four weeks after validation for unsent rows, the retry date for unknowns, and at once for unsent rows at any domain that hard-bounces during the send.

ScraperCity Implementation

ScraperCity's validator dedupes the submitted array and bills unique addresses. Dedupe on your side anyway: the email_key rule in step 3 catches Gmail dot and case variants an exact match misses, and the count you quote the user should equal the count on the bill. The start response returns emailCount and an estimatedCost; compare emailCount with your unique count before letting a large run continue, and cancel_run if they disagree.

MCP call for a small list:

{ "emails": ["[email protected]", "[email protected]", "[email protected]"] }

CLI for a large file (the file must hold one address per line; the CLI keeps any line containing @, so a multi-column CSV would send whole lines):

npx scrapercity email-validate --file chunk_01.txt
npx scrapercity poll <runId>
npx scrapercity download <runId> -o chunk_01_results.csv

Worked cost estimate

A 12,400-row event and webinar list, last mailed 14 months ago (tier C):

Validating before suppression would have billed at least 480 more addresses (402 suppressed, 17 network-role, 61 broken), $0.81, plus up to 1,388 near-duplicates that the validator's own dedupe may not merge (case variants, Gmail dots and +tags), up to $2.35 more. Show this table and wait for a yes before submitting.

Error handling

Output Format

1. send_ready.csv: valid only, columns per references/list-quality-standard.md section 2 plus email_status, email_status_raw, email_quality, email_validated_at, is_role, is_free, fix_applied.
2. catch_all.csv, hold_unknown.csv, role_review.csv: same columns.
3. removed.csv: every dropped row with removed_reason (no_email, syntax, duplicate, unsubscribed, bounced, complained, customer, competitor, network_role, invalid, disposable).
4. suppression_additions.csv: invalid and disposable addresses formatted for the sequencer's blocklist import.
5. The report from templates/output-template.md: list profile, cleaning funnel, validation results, segment files, suppression additions, cost, re-validation schedule, next steps.

Small jobs (a handful of addresses, "are these 12 safe to send"): skip the files and the report. Return one table with each address, its email_result, email_quality and the action (send, separate catch-all campaign, retry on a date, remove), then one line with the cost.

• What the reader receives is the deliverable only, in product names (Lead Database, Email Validator, Email Finder, Mobile Finder, Website Finder): no tool ids, JSON tool calls, run IDs, skill names, file paths, reference section numbers or runbook IDs; a downstream step is written out as the checks or commands the team runs, never handed to another skill by name; no tables of checks that were not run (one "Not checked:" line instead); and no repeated identical rows where one template plus a list will do. scripts/check-output.py fails a report that carries a tool id, skill name or path.

Quality Check

• Every input row appears in exactly one output file; file row counts sum to the raw row count plus rows created by splitting multi-address cells.
• No row reached the validator before dedupe and suppression.
• Validation buckets sum to the number validated, and the billed count equals the unique count.
• send_ready.csv is 100% valid, validated within four weeks, with 0 duplicates and 0 suppression matches.
• No abuse@, postmaster@, noc@, security@ or hostmaster@ address in any send file.
• Catch-all rows sit in their own file, ordered by evidence, with the user's daily volume and the 2% bounce stop written in the report.
• check_wallet ran and the user approved the cost before the run.
• scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• cold-email-list to rebuild a list when this one comes back mostly invalid.
• crm-enricher to find replacement emails and write results back to the CRM.
• icp-list-builder for new contacts that match the same profile.
• email-deliverability when bounces persist on a cleaned list.
• sending-platforms for blocklist import and auto-pause settings.
• scrapercity-cli for every CLI command and flag.