mailValidator 0.3.0.0

Verify email addresses via DNS and SMTP, with disposable/temp-mail domain detection.

mailValidator

Version: 0.2.7.0

Python package to verify email addresses using DNS and SMTP checks, with disposable/temp-mail domain detection, catch-all detection, and a CLI.

Features

• DNS verification — resolves MX records (with A/AAAA fallback per RFC 5321)
• SMTP verification — validates mailboxes without sending email
• Disposable/temp-mail detection — bundled blocklist (~72k domains); early 202 response skips DNS/SMTP for known domains
• Catch-all detection — status 201 when a domain accepts all addresses
• Organization policy blocks — status 203 when SMTP servers block external verification
• Whitelist/blacklist — configurable email and domain lists
• CLI — batch validation with grouped or table output; export to .txt or .xlsx
• Python API — verify_email() and verify_emails_list()

Installation

pip install mailValidator

For development:

git clone <repository-url>
cd emailValidator
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quick start

CLI

mailValidator --emails [e-mail],[e-mail] --format table

mailValidator --emails emails.txt --output results.txt --timeout 10
mailValidator --emails emails.txt --format table --output results.xlsx

Python

from mailValidator import verify_email

print(verify_email("[e-mail]"))
# {'status': '200', 'message': 'Valid email'}

print(verify_email("[e-mail]"))
# {'status': '202', 'message': 'Valid email but domain is temporary/disposable.'}

CLI reference

Option	Description
--emails	Comma-separated emails or path to a .txt file (one email per line)
--timeout	SMTP timeout in seconds (default: 5)
--output	Save results to .txt or .xlsx
--format	grouped (default) or table (Email | Status | Message)

Response model

Every validation returns a dict:

{"status": "<code>", "message": "<description>"}

Status	Meaning
200	Valid email (SMTP accepted or whitelisted)
201	Valid email, but domain is a catch-all
202	Disposable/temp-mail domain (checked early; DNS/SMTP skipped for blocklisted domains)
203	Organization blocks external email verification
400	Invalid email format or mailbox unavailable
403	Email or domain is blacklisted
404	Mail server not found (no MX/A/AAAA)
500	Internal or SMTP server error
502	IP blocked by Spamhaus
503	Network connection error

Configuration

Pass a config dict to verify_email() or verify_emails_list():

from mailValidator import verify_email

config = {
    "timeout": 10,
    "whitelisted_emails": ["[e-mail]"],
    "blacklisted_emails": ["[e-mail]"],
    "whitelisted_domains": ["trusted.com"],
    "blacklisted_domains": ["spam.com"],
    "additional_disposable_domains": ["custom-temp.example"],
    "additional_org_block_patterns": ["custom policy pattern"],
}

result = verify_email("[e-mail]", config)

Disposable detection notes

• Domains in the bundled blocklist or additional_disposable_domains return 202 immediately (no DNS/SMTP).
• Domains not in the blocklist are validated normally and may return 200 or 201 even if they are temp-mail providers in the real world.
• Add missing domains via additional_disposable_domains or extend disposable_domains.txt in source.

Programmatic usage

from mailValidator import verify_email, verify_emails_list

# Single email
result = verify_email("[e-mail]")

# Batch
results = verify_emails_list(
    ["[e-mail]", "[e-mail]"],
    config={"timeout": 5},
)
# {'[e-mail]': {'status': '200', 'message': '...'}, ...}

Development

pip install -e ".[dev]"
pytest -v

Build a wheel locally:

pip install build
python -m build
pip install ./dist/mailvalidator-0.2.7.0-py3-none-any.whl

See test-case.md for the full test catalog.

Changelog

See CHANGELOG.md.

License

Proprietary — see LICENSE.txt.

Copyright (c) 2024 Anu T