Metadata-Version: 2.4
Name: email-span-filter
Version: 0.1.0
Summary: Detect disposable email addresses with domain, MX, pattern, and RBL checks.
Author: Email Span Filter contributors
License-Expression: MIT
Keywords: email,disposable-email,fastapi,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: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: python-dotenv>=1.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.27; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Email Span Filter

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

## Features

- Python package API for direct use in applications
- FastAPI app for HTTP usage
- Domain-level caching with `diskcache`
- Input validation and normalized email output
- No raw email addresses in server error logs

## Clone And Run

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

Open `http://127.0.0.1:8000/docs` for the API docs.

## API Usage

```bash
curl "http://127.0.0.1:8000/email_checker/?email=test@gmail.com"
```

Example response:

```json
{
  "email": "test@gmail.com",
  "is_disposable": false,
  "reason": "Known not disposable domain"
}
```

## Python Package Usage

Install from a local clone:

```bash
pip install -e .
```

Use it in Python:

```python
from email_span_filter import check_email, is_disposable_email

result = check_email("test@gmail.com")
print(result.is_disposable, result.reason)

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

## 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 ".[api,dev]"
pytest
```

## Publishing

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

## Project Structure

```text
src/email_span_filter/
  api.py       # FastAPI application
  checker.py   # Reusable package logic
tests/
  test_checker.py
```

## License

MIT
