If you’re sitting on a big email list that’s getting stale, you already know the pain: bounces, spam complaints, wasted marketing spend. The manual cleanup is tedious, and half the tools out there overpromise and underdeliver. This guide is for anyone who wants a practical, code-driven way to automate email list cleaning using the Truemail API. Whether you run a SaaS, an ecommerce shop, or just want fewer headaches, you’ll get real steps—no fluff, no magic “AI-powered” promises.
Let’s cut through the hype and set up a workflow that actually works.
Why Clean Your Email List (and Why Automate It)
If you’re here, you probably know the basics: dirty lists mean more bounces, deliverability issues, and your emails landing in the spam folder. What gets less attention is how quickly lists get messy—even with double opt-in. People mistype. Mailboxes get abandoned. Some just enter fake addresses to grab a freebie.
Manual scrubbing might work for a list of 50. But if you’re dealing with thousands, or you want to make cleaning a habit (not a one-off chore), automation is the only sane option.
What automation gets you: - No more CSV-wrangling every time you send a campaign. - Consistent, repeatable results. - The chance to catch bad emails before they’re part of your workflow.
Step 1: What You Need Before You Start
Before you start wiring things up, make sure you’ve got:
- A Truemail API account: Sign up, get your API key, and make sure you understand your plan’s limits. Most APIs charge per verification.
- A list of emails: This guide assumes you have a CSV or database of emails to check.
- A basic scripting setup: Python is a solid choice. You don’t need to be a dev, but you should be comfortable running scripts.
- A dose of realism: No API is perfect. Some “valid” emails will still bounce, and some junk will slip through. The goal is better, not perfect.
Step 2: Know What Truemail Actually Checks (And What It Doesn’t)
Let’s be clear: Truemail isn’t psychic. It can check if an email address looks real, if the domain exists, and if the mailbox probably accepts mail—but it can’t guarantee delivery. Here’s what Truemail gives you:
- Syntax check: Catches obvious typos (missing “@,” etc).
- Domain/MX check: Makes sure the mail server exists.
- Mailbox check: Tries to verify if the address could actually receive email (though some servers block this).
- Role-based address detection: Flags generic emails like “info@” or “admin@”.
What it won’t do: - Tell you if an inbox is monitored or if a user will read your mail. - Predict the future (no tool can). - Fix typos or guess real emails from garbage.
Bottom line: Use Truemail as a filter, not a crystal ball.
Step 3: Set Up Your Script to Call the Truemail API
Let’s get hands-on. Here’s how you can wire up a simple script to clean a list of emails with the Truemail API.
Assumptions:
- You’ve got a file called emails.csv with a column of email addresses.
- You have your Truemail API key.
Install Requirements
You’ll need Python 3 and the requests library:
bash pip install requests
Sample Script
python import csv import requests import time
API_KEY = "YOUR_TRUEMAIL_API_KEY" API_URL = "https://truemail.io/api/v1/verifier"
def verify_email(email): headers = {"Authorization": f"Bearer {API_KEY}"} payload = {"email": email} try: response = requests.post(API_URL, headers=headers, json=payload) data = response.json() return data # Returns dict with verification result except Exception as e: print(f"Error verifying {email}: {e}") return None
with open("emails.csv", newline="") as infile, open("cleaned_emails.csv", "w", newline="") as outfile: reader = csv.DictReader(infile) writer = csv.DictWriter(outfile, fieldnames=reader.fieldnames + ["truemail_status"]) writer.writeheader() for row in reader: email = row["email"] result = verify_email(email) if result: status = result.get("result", "unknown") row["truemail_status"] = status # Filter out invalid or risky emails, keep valid if status == "valid": writer.writerow(row) time.sleep(1) # Avoid hitting rate limits
Pro tips: - Always check the API docs for any changes: endpoints, payload, or rate limits. - Truemail (like most APIs) has rate limits. If you’re cleaning a huge list, add delays or batch requests. - Don’t just delete everything that isn’t “valid.” Sometimes, “catch-all” domains (like corporate email servers) return “unknown.” Decide what risk you’re comfortable with.
Step 4: Automate the Workflow—Don’t Just Run It Once
One-off cleaning is better than nothing, but the real power is in automation. Here’s how to make this part of your routine:
- Hook into sign-up flows: Validate new emails as users enter them, not just in bulk.
- Schedule regular cleanups: Use cron jobs (Linux/macOS) or Task Scheduler (Windows) to re-verify your list every month or quarter.
- Integrate with your CRM or ESP: Most major platforms (Mailchimp, SendGrid, etc.) have APIs. Build scripts that pull down lists, clean them, and push back the results.
Example cron job to run your script nightly: bash 0 2 * * * /usr/bin/python3 /path/to/your/script.py
(Runs every night at 2am)
Watch out for: - API costs: Automating at scale means more API calls (and higher bills). Monitor usage. - Data privacy: Don’t send sensitive or unnecessary data to third parties. Stick to email addresses.
Step 5: How to Handle the “Gray Area” Results
Not every email will be labeled “valid” or “invalid.” You’ll see results like “unknown” or “accept-all.” Here’s how to handle them:
- Valid: Keep them. These are the best bets.
- Invalid: Remove or suppress. These will almost always bounce.
- Accept-all/Catch-all: These domains accept any email, so you can’t be sure if the address is real. Some are good, some are honeypots. If you’re risk-averse, suppress them.
- Unknown/Timeouts: Could be temporary issues or anti-spam blocks. If they matter, try again later or flag for manual review.
Don’t obsess about clearing every single unknown. Some companies intentionally make it hard to check. Focus on getting rid of the obvious garbage first.
Step 6: What to Ignore (And What Not to Worry About)
There’s a lot of noise in email validation. Here’s what you can safely skip:
- “Disposable” address detection: Truemail can flag these, but unless you’re running a freebie campaign, don’t stress—some are legit users.
- Social media checks: Some tools brag about “social media lookup.” This is mostly fluff and rarely actionable.
- “Deliverability scoring”: These are guesses, not facts. Ignore the fancy numbers—stick to clear-cut results.
Remember, most of your gains come from catching the obvious bad emails. The diminishing returns on hyper-granular filtering just aren’t worth the headache.
Step 7: Monitor, Iterate, and Keep It Simple
Once your workflow is up, don’t just set it and forget it. Watch your bounce rates and feedback loops. If you find a pattern (like a certain ESP blocking verification), tweak your script or settings.
Checklist for a healthy workflow: - Spot-check cleaned lists now and then. - Monitor your API usage and costs. - Update your script if Truemail changes their API.
Resist the urge to over-engineer. Automation is supposed to save time, not create a new monster to maintain.
Wrapping Up: Keep Your Email List Lean and Useful
You don’t need fancy “AI” or enterprise-grade tools to keep your email list clean. A simple workflow with Truemail, a bit of scripting, and a regular schedule will get you 90% of the way there. Focus on the basics, ignore the hype, and iterate as you go. The less time you spend wrangling bad emails, the more you can spend actually reaching your customers.
Good luck—and keep it simple.