Temp Email Filter

Temp Email Filter is a Python package for detecting disposable email addresses. It performs comprehensive checks including known disposable domains, trusted provider validation, email patterns, MX record validation, blocked MX hosts, and DNS-based RBL (Real-time Blackhole List) services.

Features

• Trusted provider check: Immediately validates emails from known legitimate providers (Gmail, Yahoo, etc.)
• Disposable domain detection: Checks against known temporary email services
• Pattern analysis: Identifies suspicious email patterns (excludes legitimate + aliases)
• MX record validation: Verifies domain has valid mail servers
• RBL checking: Queries reputation databases using proper IP-based lookups
• Intelligent caching: Caches both positive and negative results for performance
• DNS timeouts: Prevents hanging on slow DNS queries
• Input validation: Normalizes and validates email format before processing

Install

pip install temp-email-filter

For local development from a clone:

git clone <your-repo-url>
cd temp_email_filter
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Basic Usage

from temp_email_filter import check_email

result = check_email("test@gmail.com")
print(f"Email: {result.email}")
print(f"Is disposable: {result.is_disposable}")
print(f"Reason: {result.reason}")

if result.is_disposable:
    print("This email should be rejected")
else:
    print("This email is acceptable")

If you only need the original tuple style:

from temp_email_filter import is_disposable_email

is_disposable, reason = is_disposable_email("test@gmail.com")

Django Example

from django.core.exceptions import ValidationError
from temp_email_filter import check_email


def validate_non_disposable_email(value):
    result = check_email(value)
    if result.is_disposable:
        raise ValidationError(result.reason)

Use the validator in a model or serializer field.

FastAPI Example

This package does not start a FastAPI server. Add it to your own FastAPI app:

from fastapi import FastAPI, HTTPException
from temp_email_filter import check_email

app = FastAPI()


@app.get("/email-checker")
def email_checker(email: str):
    result = check_email(email)
    if result.reason.startswith("Invalid email"):
        raise HTTPException(status_code=400, detail=result.reason)

    return {
        "email": result.email,
        "is_disposable": result.is_disposable,
        "reason": result.reason,
    }

Running As A Service

This project is package-only. To run it as a service, install it inside your own Django, FastAPI, Flask, worker, or microservice project and call check_email() from your route, form validation, serializer, or background job.

Configuration

The cache directory defaults to .email_cache. Override it with:

export TEMP_EMAIL_FILTER_CACHE_DIR=/tmp/temp-email-filter-cache

Recent Improvements (v0.1.1)

• Fixed RBL checking: Now properly queries MX record IPs instead of domains
• Improved pattern matching: Removed false positive for legitimate + aliases (john+work@gmail.com)
• Enhanced caching: Now caches both disposable and legitimate results
• Better logic flow: Trusted providers checked first, bypassing expensive DNS operations
• DNS timeouts: Added configurable timeouts to prevent hanging queries
• Transient error handling: Avoids caching temporary DNS failures

Development

pip install -e ".[dev]"
pytest

Publishing

Maintainer release steps are documented in docs/PYPI.md.

License

MIT