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 / Docs

Email List Cleaner: setup guide

One list export becomes clean.csv with your original columns, removed.csv with a reason for each address set aside, 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 and top-level domain). Domains are lowercased. Duplicates are caught regardless of case. Likely typos of common providers (gmial, hotmial, .con) are flagged with a suggested fix. Role inboxes (info@, sales@, noreply@) and known throwaway domains are set aside as risky, and placeholder domains are invalid. Runs fully offline 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

5-minute setup

  1. Claude.ai: open Settings → Capabilities → Skills, click Upload skill and pick claude-ai-upload/email-list-cleaner.zip.
  2. Claude Code: copy the folder skills/email-list-cleaner into ~/.claude/skills/.
  3. Start a new chat. Attach your file and say: "Use email-list-cleaner. Clean this subscriber export before my newsletter".
  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 (22 fictional subscribers on reserved .test domains):

python3 skills/email-list-cleaner/scripts/core.py samples/subscribers.csv --out out

You should see 13 kept, 6 invalid, 1 duplicate and 2 role inboxes set aside.

Settings you can change

Option Default What it is
list (required) CSV export (comma, semicolon, tab or pipe) or one-address-per-line file
--column (auto) Name of the email column if it is not found automatically
--keep-risky (off) Keep typo, role and throwaway addresses in clean.csv
--out out Output folder

What goes in and what comes out

Inputs: One CSV export (any delimiter) or a one-address-per-line file

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

What Pro adds

  • Fix domain typos automatically, including near-misses of your customers' domains
  • Your suppression list (unsubscribes, bounces, whole @domains) and your own block/allow lists
  • Gmail dot and +tag duplicates
  • DNS mail-server check: drop domains that do not exist or cannot receive mail
  • Merge several exports into one clean list

Pro: https://oarsmanai.com/agents/email-list-cleaner-pro/

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: - Typos are suggested, not fixed (Pro fixes them). - No suppression list, no mail-server check and one list at a time (Pro). - It cannot prove a mailbox exists; it never contacts mail servers.

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-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.