email-safeguard 0.1.6

A Python library for validating and suggesting corrections for email addresses.

Email Safeguard

A comprehensive email validation library that provides domain suggestions, disposable email detection, and MX record validation with a focus on security and user experience.

Features

• 🔍 Smart validation with helpful suggestions
• 🛡️ Disposable email detection
• 📨 MX record validation
• ⚡ Fast and customizable
• 🎯 Type hints and modern Python support
• 🔧 Configurable validation rules

Installation

pip install email-safeguard

Quick Start

from email_safeguard.validator import EmailSafeguard

validator = EmailSafeguard()
result = validator.validate("[e-mail]")

if result.is_valid:
    if result.suggestions:
        print(f"Email is valid but did you mean: {result.suggestions.get('domain')}?")
    else:
        print("Email is valid!")
else:
    print(f"Error: {result.message}")

Advanced Usage

Custom Configuration

validator = EmailSafeguard(
    check_mx=True,              # Enable MX record validation
    allow_disposable=False,     # Reject disposable emails
    suggest_corrections=True,   # Suggest corrections for typos
    max_distance=2             # Maximum edit distance for suggestions
)

Handling Results

from email_safeguard.validator import EmailSafeguard, ValidationResult

validator = EmailSafeguard()
result = validator.validate("[e-mail]")

# Check the validation result
if result.result == ValidationResult.VALID:
    print("Email is valid!")
elif result.result == ValidationResult.DISPOSABLE:
    print("Disposable emails not allowed")
elif result.result == ValidationResult.INVALID_DOMAIN:
    if result.suggestions and 'domain' in result.suggestions:
        print(f"Invalid domain. Did you mean: {result.suggestions['domain']}?")
elif result.result == ValidationResult.NO_MX_RECORD:
    print("Domain has no mail server")

ValidationResult Types

The library provides several validation result types:

from email_safeguard.validator import ValidationResult

# Available validation results:
# ValidationResult.VALID
# ValidationResult.INVALID_FORMAT
# ValidationResult.INVALID_DOMAIN
# ValidationResult.INVALID_TLD
# ValidationResult.DISPOSABLE
# ValidationResult.NO_MX_RECORD
# ValidationResult.TIMEOUT

Validation Response

The validate() method returns a ValidationResponse object with the following attributes:

class ValidationResponse:
    is_valid: bool              # Whether the email is valid
    result: ValidationResult    # The specific validation result
    message: str               # A descriptive message
    suggestions: Optional[Dict[str, str]]  # Suggested corrections if any

Data Files

The library uses three customizable data files:

• popular_domains.txt: Common email domains
• popular_tlds.txt: Valid top-level domains
• disposable_domains.txt: Known disposable email providers

Custom Data Files

validator = EmailSafeguard(data_dir="path/to/data/directory")

Development

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=email_safeguard

Type Checking

mypy email_safeguard

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Chukwuka Ibejih ([e-mail])

Acknowledgements

Built with:

• Django - Email validation
• python-Levenshtein - String similarity
• dnspython - DNS queries

---

If you find this library helpful, please give it a ⭐!