Free agents + LAUNCH30: 30% off paid agents until 31 Dec 2026 (one-time purchases only) See free agents
Oarsman AI Sign in

Email List Cleaner Pro with MX check / Docs

Email List Cleaner Pro with MX check: setup guide

One or more list exports become clean.csv (your original columns, ready to import), removed.csv with a reason for every address set aside, all-with-status.csv and a short report.

Who it is for: Founder, marketer or VA at a small business who exports a mailing list from a CRM, signup form or event and wants it clean before a newsletter or campaign, without paying per address.

Format: Claude skill pack · Version: 1.0.0 · Tested on: Python 3.13.5 (standard library only)

What it does

Every address is cleaned of 'Name

' and mailto: wrappers and checked for syntax (one @, up to 64 characters before it and 254 in all, valid domain labels and top-level domain). Domains are lowercased. Likely typos of common providers (gmial, hotmial, .con) and of your known domains are flagged with a suggestion, or corrected with --fix-typos. Duplicates are caught regardless of case, and with --gmail-dupes dots and +tags count as the same mailbox where the provider does that. Your suppression list removes addresses and whole @domains. Role inboxes (info@, sales@, noreply@) and throwaway domains (a built-in list plus yours) are set aside as risky. With --check-mx each domain's MX record is looked up over DNS-over-HTTPS: domains that do not exist, have no mail server or publish a null MX are marked invalid. It never connects to a mail server and never sends anything.

What you need

  • Claude.ai with code execution switched on (or Claude Code, or just Python 3.10+)
  • Your list export
  • Internet access only if you use --check-mx (DNS lookups)

5-minute setup

  1. Claude.ai: open Settings → Capabilities → Skills, click Upload skill and pick claude-ai-upload/email-list-cleaner-pro.zip.
  2. Claude Code: copy the folder skills/email-list-cleaner-pro into ~/.claude/skills/.
  3. Start a new chat. Attach your file and say: "Use email-list-cleaner-pro. Clean these two signup exports before Friday's newsletter, apply my unsubscribes and check the mail servers".
  4. Claude runs the script and gives you the files listed under Outputs. Check them before you act on them.

Try it with the sample

Run the sample (two fictional signup lists, an unsubscribe list, a throwaway-domain blocklist and the domains your customers use):

python3 skills/email-list-cleaner-pro/scripts/core.py samples/subscribers.csv samples/event-signups.csv --suppression samples/unsubscribes.csv --blocklist samples/blocklist.txt --known-domains samples/known-domains.csv --fix-typos --out out

You should see 26 addresses: 12 kept, 6 invalid, 2 duplicates, 2 suppressed and 4 risky (3 role inboxes, 1 throwaway), with one domain typo fixed. The sample uses reserved .test domains, so run --check-mx on your own list, not the sample.

Settings you can change

Option Default What it is
lists (required) One or more CSV exports (comma, semicolon, tab or pipe) or one-address-per-line files
--column (auto) Name of the email column if it is not found automatically
--fix-typos (off) Correct likely domain typos instead of flagging them
--gmail-dupes (off) Treat dots and +tags as the same mailbox where the provider does
--suppression (optional) Addresses or @domains never to email again
--blocklist / --allowlist (optional) Extra throwaway domains to flag / domains never flagged
--known-domains (optional) Domains your list should contain; near-misses are typos
--check-mx (off) Look up each domain's mail servers over DNS-over-HTTPS (needs internet; sends domain names only)
--keep-role / --keep-risky / --strict (off) Do not flag role inboxes / keep risky in clean.csv / count throwaway as invalid
--out out Output folder

What goes in and what comes out

Inputs: One or more CSV exports (any delimiter) or a plain one-address-per-line file; Optional: suppression list (unsubscribes, bounces, complaints; addresses or @domains); Optional: your own throwaway-domain blocklist, an allowlist, and the domains your customers use

Outputs: clean.csv with your original columns; removed.csv with status, reason and a suggested fix; all-with-status.csv; report.md with counts, reasons and top domains

AI disclosure and limits

This product does not call an AI model at run time. It was built by Oarsman AI's AI agents and checked by the automated tests shipped with it.

Limits: - It cannot prove a mailbox exists: it never probes mail servers (that is how verification services get blocked). Expect a few bounces; add them to your suppression list. - Catch-all domains and full mailboxes are not detected. - The built-in throwaway list is small and hand-picked; add your own with --blocklist. - --check-mx needs internet access for DNS lookups; everything else runs offline.

Not tested by us: - lists over 200,000 rows (works, but slower) - every CSV dialect of every email tool - internationalised addresses beyond IDNA domains

Files

  • oarsman-email-list-cleaner-pro-v1.0.0.zip
  • CHANGELOG.md
  • QA-REPORT.json
  • README.md
  • SPEC.md
  • SUPPORT.md
  • TROUBLESHOOTING.md
  • VERSION
  • VIDEO-SCRIPT.md
  • claude-ai-upload
  • diagram.mmd
  • diagram.png
  • preview.png
  • samples
  • skills
  • tests

Help

Self-serve: see TROUBLESHOOTING.md (fixes and FAQ). There is no call, chat or email support. Fixes ship as new versions at your download link. Refund: 14 days, works as described, through the checkout platform.