Metadata-Version: 2.4
Name: email-spam-filter
Version: 0.1.2
Summary: Detect disposable email addresses with domain, MX, pattern, and RBL checks.
Author: Email Spam Filter contributors
License-Expression: MIT
Keywords: email,disposable-email,validation,dns,spam
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: diskcache>=5.6
Requires-Dist: dnspython>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Email Spam Filter

Email Spam 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

```bash
pip install email-spam-filter
```

For local development from a clone:

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

## Basic Usage

```python
from email_spam_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:

```python
from email_spam_filter import is_disposable_email

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

## Django Example

```python
from django.core.exceptions import ValidationError
from email_spam_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:

```python
from fastapi import FastAPI, HTTPException
from email_spam_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:

```bash
export EMAIL_SPAM_FILTER_CACHE_DIR=/tmp/email-spam-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

```bash
pip install -e ".[dev]"
pytest
```

## Publishing

Maintainer release steps are documented in [`docs/PYPI.md`](docs/PYPI.md).

## License

MIT
