Terminal
Terminal/Skill
Sorts a list of email addresses into keep, risky and remove groups with a reason for each removal, checking free rules before paid validation.
By Clay
Works with
npx skills add clay-run/clay-skill-creator --skill clean-email-listThe insight: a list's value is set by its worst segment. Bounce rate is measured over the whole send — a few percent of dead rows can gate the other 95% out of inboxes. So cleaning is triage, not filtering: every input row lands in exactly one of keep / risky / remove / could-not-verify, with quoted evidence, and rows are never silently deleted — a row you can't account for is a row you can't defend. The other half is ordering: every free deterministic pass runs before the first paid call, so the validator only ever sees rows that could still be sendable.
Nothing here ships with a value. Each one is the installer's, not the author's: ask for it, never substitute a plausible default, and where an answer does not exist say which step becomes unavailable rather than guessing. Where a default IS defensible it is named below, and using it means saying so in the output.
| Input | What the installer supplies | If it is missing |
|---|---|---|
| The list | a CSV or table, and which column holds the email | no default, and no other column is ever edited |
| The purpose | cold volume send, CRM refresh, or re-engagement | ask — it decides the policy: for cold sends role mailboxes are removed and freemail is risky; for the others both are only risky |
| Budget | credits for paid validation after the free passes | free passes run regardless; state the cost of what survives them before spending |
If an answer sheet is present beside this skill, load it and ask only for what it does not cover. A partial sheet is normal; a value it is missing gets asked for on its own rather than restarting the interview. Say which values came from the sheet before using them — a sheet applied silently is a wrong field nobody catches. If there is no sheet, say nothing about sheets — the check is a file lookup, not a question, so run the interview as though the feature did not exist rather than reporting an absence. At delivery, offer to save the answers back (identifiers only — never a token or a password), private and never published — and phrase the offer so it explains itself: "want me to save your answers to a file, so the next person on your team doesn't have to answer these again?"
Run clay whoami; echo "exit_code=$?". If it fails or Clay tools are missing, run the
Clay plugin's setup skill (or follow
https://raw.githubusercontent.com/clay-run/agent-plugins/main/GETTING_STARTED.md),
restart if told to, and re-run. Tell the user which workspace you're in.
info@, support@…) go to
remove and personal/freemail goes to risky; for other purposes both go to risky.Run in order, recording per-row reason + evidence at each:
remove: duplicate with a
pointer to the kept row.@ one domain with a dot, no spaces — a cheap structural
check, not full RFC. Failures → remove: syntax-invalid, quoting the string. Never
"fix" a typo and keep the fixed version silently.support@ box may be genuinely read).remove: disposable.0 .) → the domain declares it takes no mail — dead even though a record exists;
real MX → survives. Dead domains → remove: dead-domain for every row on them,
quoting the DNS answer. This kills paid calls on dead rows for free.Run extract-email-components (Clay action; catalog tier 1) per surviving row: it
returns domain plus isLikelyPersonalEmail / isLikelyCompanyEmail /
isLikelyEducationEmail. Personal → risky under a cold-send policy. Read the actual
charge from run usage metadata (verified at 0 credits + 0 action executions in one
workspace — but read it, don't assume).
Pick a validator from the live catalog (clay workflows actions list), lowest
priorityTier that separates catch-all from valid (tier 2 is typically ZeroBounce
validate-email or enrichley-verify-email, ~0.1 credits/check). State survivor
count × per-check cost and get approval before running. Then call it per row (Clay
MCP execute_clay_action); checks return in seconds for every verdict. Map field
PAIRS, never one field — vocabularies invert across validators: ZeroBounce puts
catch-all at status: valid + sub_status: catch_all; Enrichley puts it at
valid: false + result: catch_all. Verdicts: plain valid (sub_status: "" — empty
string) → keep; catch-all → risky (Enrichley's catch_all_validated upgrade =
keep, probe-confirmed); do_not_mail / suppression / disposable sub-statuses →
remove, quoting the sub-reason; invalid → remove; unknown, timeouts, empty
payloads → could-not-verify — never rounded either way. Fuse validator with
classifier: a freemail address can validate as deliverable (observed live: valid /
sub_status: alternate + free_email: true on a Gmail address) — a mailbox verdict
never overrides the policy segment. Run status is not data: it reports SUCCESS for
every verdict. For many hundreds of rows or a recurring clean,
build it as a Clay table/workflow instead and say so.
unknown /
mail_server_temporary_error, which is retryable later; the user decides whether to
spend more checks.email · normalized · segment · reason · evidence · duplicate_of · provider.Ask: "Clean this 500-row conference list for a cold send." Free passes: 62 duplicates, 8 syntax-invalid, 41 role, 5 disposable, 37 on dead domains (3 of them null-MX) — 347 survive, zero credits. Classify: 29 personal → risky. Validation quote: 347 × ~0.1cr ≈ 35 credits — approved. Result: 214 keep, 71 risky (29 personal + 42 catch-all), 203 remove, 12 could-not-verify. 500 = 214 + 71 + 203 + 12 ✓. Recommendation: send to keep; Enrichley-escalate the 42 catch-alls (~4 credits) if the list matters.