Metadata-Version: 2.4
Name: email-span-filter
Version: 0.1.1
Summary: Detect disposable email addresses with domain, MX, pattern, and RBL checks.
Author: Email Span 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 Span Filter

Email Span Filter is a Python package for detecting disposable email addresses. It checks known disposable domains, safe common domains, email patterns, MX records, blocked MX hosts, and DNS-based RBL services.

## Install

```bash
pip install email-span-filter
```

For local development from a clone:

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

## Basic Usage

```python
from email_span_filter import check_email

result = check_email("test@gmail.com")

if result.is_disposable:
    print(result.reason)
```

If you only need the original tuple style:

```python
from email_span_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_span_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_span_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_SPAN_FILTER_CACHE_DIR=/tmp/email-span-filter-cache
```

## Development

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

## Publishing

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

## License

MIT
