email_verification v1.0.0

name: email_verification description: Verify email addresses before a send or signup: layered syntax, domain and MX, SMTP probe, and catch-all checks, with a result class and a concrete action for every address. Use when cleaning a mailing list, validating signups in real time, checking a single address, deciding what to do with risky, unknown, or catch-all results, or diagnosing why verification disagrees with actual bounces.

Email Verification

Purpose

Decide, for each address, whether to send, hold, or exclude, and be able to show the evidence behind the decision. Verification is layered because each layer proves a different thing: syntax proves the address is well formed, MX proves the domain can receive mail, an SMTP probe suggests the mailbox exists. No layer proves consent, and no result guarantees delivery. Treat every result as a risk call made at the time of the check, not a fact about the future.

The bundled checker is bin/verify_email.py. It runs the syntax, domain, flag, and (with --smtp) probe layers and prints a result class plus an action for each address. It never sends mail; the probe stops before DATA.

Workflow

1. Fix the decision rules before touching the list. Write down what happens to each result class (table below) for this send. A high-value flow (account signup, transactional) is stricter than a low-risk one (newsletter re-engagement). Rules decided after seeing results get bent; rules decided before do not.
2. Dedupe and suppress first. Remove exact duplicates, then remove anyone with a prior unsubscribe, spam complaint, or permanent bounce, keeping the reason and date. Verification never overrides a suppression. A technically valid address the person asked you to stop mailing stays suppressed.
3. Run the cheap layers on everything. Syntax, domain, and MX checks, plus disposable, role, and typo flags: python3 bin/verify_email.py --file list.csv --json Exclude syntax failures, domains with no MX, and domains publishing a null MX (RFC 7505: a single MX record pointing at "." with preference 0, which declares the domain accepts no mail). Offer typo suggestions (person@gmial.com to person@gmail.com) back to the user at a form; never silently rewrite an address in a stored list.
4. Probe only where the answer changes the action. SMTP probing is slow, many large providers block or throttle it, and some receiving servers punish probing IPs. Probe the addresses that passed step 3 when mailbox existence matters: python3 bin/verify_email.py --smtp --file shortlist.txt --json. Read references/smtp-probing.md before probing at any volume.
5. Classify every address and act by class. Use the table in the Output Contract. Split the output into per-class files or segments so the send, the hold queue, and the exclusion list are separate artifacts someone can audit.
6. Send in a cautious first batch and watch real outcomes. Start with the valid segment, watch hard bounces and complaints, and only then consider mailing a held segment (for example engaged contacts on catch-all domains). Real bounce data outranks any probe result; feed permanent bounces back into the suppression list the same day.
7. Re-verify on a cycle. Mailboxes get disabled and domains lapse. An address verified a year ago is a stale claim. Re-run layers 3 to 5 before a large send to an old list, and treat long-inactive addresses as a spam-trap risk (see Operating Rules), not just a bounce risk.

Output Contract

Every verification run returns, per address: the address, each check's raw result, any flags, one result class, one action, and a plain reason. Classes and default actions:

| Class | Meaning | Default action | |---|---|---| | valid | Syntax and MX pass, SMTP probe accepted, domain is not catch-all | Send, starting with a cautious first batch | | unverified | Syntax and MX pass, no probe evidence either way | Confirm ownership (double opt-in or confirmation mail) or probe before sending at scale | | invalid | Bad syntax, no MX, null MX, SMTP 5xx rejection, or disposable domain | Exclude; do not mail, do not keep re-testing | | risky: catch-all | Domain accepts arbitrary addresses, so mailbox existence cannot be confirmed | Hold for source and engagement review; mail only engaged contacts, small batches | | risky: role | Local part is a function (info@, support@, admin@) | Segment separately; fine for B2B function mail, wrong for a named-person campaign | | risky: mailbox full | SMTP 552 | Hold and retry later; one full reading is not a dead mailbox | | unknown | Probe or DNS gave no reliable answer (4xx, timeout, blocked probe) | Hold and retry after a delay; unknown is not invalid |

Worked case: a 1,000-row documented signup list. 60 duplicates and 30 suppression matches come out first. Verification marks 25 invalid syntax or dead domains, 15 disposable, 20 catch-all or unknown. That leaves 850 rows for the cautious first batch, assuming the permission record for those rows checks out. The 20 held rows get reviewed by source and last engagement, not mailed on hope.

Operating Rules

• Never treat a single check as the verdict. MX alone misses dead mailboxes on live domains; an SMTP 250 alone misses catch-all domains that accept everything.
• Catch-all test: when a probe is accepted, probe one random clearly fake local part at the same domain. If that is accepted too, the domain is catch-all and the first result proves nothing about the mailbox.
• Respect what 4xx means. Codes 450, 451, and 452 and enhanced code 4.7.1 usually mean greylisting, throttling, or a temporary fault. Retry after a delay. Converting a 4xx into invalid deletes real subscribers; converting it into valid invents evidence.
• 5xx at RCPT TO (550, 551, 553, 554) means the server refused that mailbox. Exclude the address. 552 means storage exceeded: hold, do not exclude on one reading.
• Know the probe's limits and say them. Gmail, Microsoft, and Yahoo often refuse or defer probes, anti-spam systems accept everything and bounce after DATA, and outbound port 25 is blocked on many networks. When the probe cannot complete, the honest class is unknown. Never report a mailbox as verified on a probe that did not finish.
• Protect the probing IP. Probe from an IP with correct reverse DNS and a real HELO name, keep per-domain concurrency low, and stop when a domain starts deferring everything. A burned probe IP produces unknowns, then blocklist entries.
• Spam traps are the cost of skipping hygiene, and verification only partly detects them. Pristine traps never belonged to a person and arrive through scraped or purchased lists. Recycled traps were real addresses, abandoned, then repurposed by the provider after a long bounce period. Typo traps sit at misspelled domains. Defenses: never buy or rent lists, use confirmed opt-in, remove hard bounces immediately, and sunset contacts with no engagement for 6 to 12 months before the provider recycles them.
• Disposable domains get excluded from sends and blocked at signup for accounts with any value. Keep the disposable list in a maintained file passed with --disposable-file; the small seed list in the script is a starter, not a database.
• Valid is not consented and not valuable. Verification measures technical quality only. Permission, relevance, and engagement are separate checks with separate evidence.
• Keep the raw check results with the class. When a sender disputes an exclusion, the MX answer, the SMTP code, and the flags are the explanation. A bare score with nothing behind it settles nothing.