Free open source tool
CSV Subscriber Cleaner
Clean and merge subscriber CSV files without uploading customer data to an external service.
- Runs locally on your computer
- Python 3.9 or newer
Clean subscriber data, on your computer
CSV Subscriber Cleaner is a free, open source Python tool for cleaning subscriber data for newsletters and email marketing. It runs locally on your computer. It combines two subscriber exports, normalises and deduplicates email addresses, applies unsubscribe and bounce rules, and creates clean import, suppression, and audit files.
Your source files remain on your computer. No customer information is uploaded to HDY Haus.
Requirements: Python 3.9 or newer. No third party packages are required.
What it helps you do
- Merge subscriber information from two CSV exports
- Consolidate duplicate email addresses
- Exclude unsubscribed, spam, hard bounced, and opted out addresses
- Preserve useful profile and activity information
- Prepare cleaned subscriber data for your newsletter platform
- Review an audit report before importing anything
Which newsletter platforms can I use it with?
The cleaning, merging, deduplication, and suppression steps are useful regardless of which newsletter platform you use. The current import file is formatted for Listmonk. For another platform, check its CSV import requirements: you may need to rename or map columns and reformat the JSON attributes column before importing. The tool does not connect to or import data into your newsletter service automatically.
How to use it, step by step
You do not need to write code. You will need to install Python and paste a few commands into Terminal or PowerShell. Try the included fictional sample files before using your own data.
1. Install Python
If you do not already have Python, download it from the official Python website and follow its installation instructions for your computer. This tool requires Python 3.9 or newer. No extra Python packages are needed.
2. Download and unzip the cleaner
Click Download the latest release. On GitHub, find Assets and download the attached ZIP whose name begins csv-subscriber-cleaner-v. You do not need a GitHub account. On Mac, double-click the ZIP. On Windows, right-click it and choose Extract All. Open the extracted folder that contains csv_subscriber_cleaner.py.
3. Open a command window in that folder
A command window is where you paste the instructions that run the cleaner.
Mac: Open the Terminal app. Type cd followed by a space, drag the extracted folder from Finder into Terminal, then press Return.
Windows: Open the extracted folder in File Explorer. Click the address bar at the top, type powershell, and press Enter.
Check that Python is available. On Mac, paste python3 --version. On Windows, paste python --version. Press Enter. You should see Python 3.9 or newer. If Windows recognises py --version instead, use py in place of python in the commands below.
4. Try the fictional sample files
Copy the command for your computer, paste it into the command window, and press Enter.
Mac:
python3 csv_subscriber_cleaner.py sample_primary.csv sample_secondary.csv --output sample_outputWindows:
python csv_subscriber_cleaner.py sample_primary.csv sample_secondary.csv --output sample_outputYou should see Processing complete, Eligible subscribers: 3, and Suppressed addresses: 1. A new folder named sample_output will appear inside the cleaner folder.
5. Prepare your two CSV exports
Export your subscriber lists as CSV files from the services you use. Work with copies and keep the original exports somewhere safe. Put the copies in the same folder as csv_subscriber_cleaner.py.
Rename the copy with the profile information you trust most to primary.csv. Rename the copy with activity and email preferences to secondary.csv. Both files must contain an email column, such as Email or Email address. Make sure the filenames do not accidentally end in .csv.csv.
When an address appears in both files, profile information normally comes from the primary file. Activity information comes from the secondary file when available. An unsubscribe, spam, hard bounce, or explicit subscription opt-out flag in either file suppresses that address.
6. Run the cleaner on your files
Mac:
python3 csv_subscriber_cleaner.py primary.csv secondary.csv --output cleaned_outputWindows:
python csv_subscriber_cleaner.py primary.csv secondary.csv --output cleaned_outputPress Enter and wait for Processing complete. Your original files stay unchanged. Results are saved in a new cleaned_output folder, separately from the sample results. Running the same command again replaces the result files in that output folder.
7. Check the results before importing
Open cleaned_output. It contains three files:
audit_report.csv: counts of input rows, invalid addresses, unique addresses, and suppressions. Review this first. Eligible unique emails plus suppressed unique emails should equal unique valid emails across both files.suppression_list.csv: excluded addresses and the reasons they were excluded. Check that the totals make sense for your data. Keep these addresses out of your import.listmonk_import.csv: the deduplicated records that passed the cleaner’s rules. The current file is formatted for Listmonk. If you use another newsletter platform, check its required columns and formatting before importing. Passing the cleaner’s rules does not confirm marketing consent.
Check that no address appears in both the import and suppression files. Only import records after checking the output and confirming that you have the appropriate permission to contact those people. Store exports and results securely, and delete working copies when you no longer need them.
If something does not work
- Python is not found: finish installing Python, close and reopen the command window, then repeat step 3. On Windows, try
py --version. - Cannot open the script or find a file: check that you unzipped the download, opened the command window in the folder containing the script, and used the exact CSV filenames shown in step 5.
- Could not find an email column: check that each CSV has a header row with a heading such as Email or Email address.
If processing reports an error, resolve it and run again before using any output. To report a bug, open a GitHub issue with the error message and fictional example data. Do not attach subscriber exports, email addresses, or customer information.
Privacy and consent
This tool helps process data. It does not determine whether you have consent to contact someone. You remain responsible for applicable privacy and email marketing requirements.
Need help with a tool or resource?
Use our product support page for help with HDY Haus plugins, tools, PDFs, guides, and other resources. Personal WordPress plugin support costs €49 per year for all our plugins across unlimited websites. We confirm any fee for resource guidance or custom work before work begins. Reports and missing purchase or download issues are free to submit.