Metadata-Version: 2.4
Name: fadsync-mailcheck
Version: 1.0.0
Summary: Ultra-fast email validation, 40M+ disposable burner email blocking, and anti-fraud auth guard for Python, FastAPI, Django, and Flask.
Author-email: FadSync <support@fadsync.com>
License-Expression: MIT
Project-URL: Homepage, https://mailcheck.fadsync.com/
Project-URL: Documentation, https://mailcheck.fadsync.com/
Project-URL: Repository, https://github.com/fadsync/python-mailcheck
Project-URL: Issues, https://github.com/fadsync/python-mailcheck/issues
Keywords: email-validation,email-verifier,disposable-email,fastapi-middleware,django-validator,fadsync,mailcheck,fraud-prevention,auth-guard,burner-email
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=1.10.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Provides-Extra: django
Requires-Dist: django>=3.2; extra == "django"
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: django>=3.2; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# ⚡ fadsync-mailcheck

[![PyPI Version](https://img.shields.io/pypi/v/fadsync-mailcheck?color=blue&logo=pypi)](https://pypi.org/project/fadsync-mailcheck/)
[![Python Versions](https://img.shields.io/pypi/pyversions/fadsync-mailcheck)](https://pypi.org/project/fadsync-mailcheck/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MailCheck](https://img.shields.io/badge/FadSync-MailCheck-00D2FF)](https://mailcheck.fadsync.com/)

**The Official Python SDK, FastAPI Guard, and Django Validator for [FadSync MailCheck](https://mailcheck.fadsync.com/).**  
Block 40M+ disposable burner email domains, autocorrect typos, verify DNS MX servers, and protect authentication pipelines with sub-50ms latency.

---

## 🚀 Features

- 🚫 **40M+ Disposable Email Detection**: Real-time identification of burner domains (*10minutemail, GuerrillaMail, Mailinator, etc.*).
- ⚡ **Sync & Async (`httpx`)**: Native asynchronous and synchronous clients for high-throughput backends.
- 🛡️ **FastAPI & Django Integrations**: 1-line route dependencies (`FastAPIEmailGuard`) and Django form/model validators.
- 💡 **Smart Typo Autocorrect**: Catches and suggests fixes for common domain mistakes (`user@gamil.com` ➔ `user@gmail.com`).
- ⚡ **Thread-Safe In-Memory Cache**: Built-in TTL caching with LRU eviction to minimize upstream API calls.
- 🔄 **Fail-Safe Resilience (`fail_silent=True`)**: Network timeouts and blips never break user signups.
- 🔑 **Direct Authentication**: Seamless connection with standard FadSync API keys (`Authorization: Bearer <API_KEY>`).
- 📘 **Fully Typed (PEP 561)**: First-class Pydantic models with complete type hints for PyCharm and VS Code.

---

## 📦 Installation

```bash
# Core SDK (Sync + Async)
pip install fadsync-mailcheck

# With FastAPI integration
pip install "fadsync-mailcheck[fastapi]"

# With Django integration
pip install "fadsync-mailcheck[django]"

# All integrations
pip install "fadsync-mailcheck[all]"
```

---

## 🔑 Getting Your API Key

1. Sign up for a free account at **[https://mailcheck.fadsync.com/](https://mailcheck.fadsync.com/)**.
2. Copy your API Key from the Developer Dashboard.
3. Pass it to the client or set the `FADSYNC_API_KEY` environment variable.

---

## ⚡ Quickstart

### 1. Synchronous Python Usage

```python
from fadsync_mailcheck import FadSyncMailCheck

client = FadSyncMailCheck(api_key="YOUR_FADSYNC_API_KEY")

result = client.verify("tester@10minutemail.com")

if result.is_blocked:
    print(f"❌ Blocked: {result.user_friendly_message}")
    # Output: "Temporary and disposable email addresses are not permitted. Please use a permanent email."
else:
    print(f"✅ Safe to register! Risk score: {result.risk_score}/100")
```

---

### 2. Asynchronous Python Usage (`asyncio`)

```python
import asyncio
from fadsync_mailcheck import AsyncFadSyncMailCheck

async def main():
    async with AsyncFadSyncMailCheck(api_key="YOUR_FADSYNC_API_KEY") as client:
        result = await client.verify("alex.hunter@gmail.com")
        print(f"Domain: {result.domain}, Has MX: {result.has_valid_mx}")

asyncio.run(main())
```

---

### 3. FastAPI Route Guard Dependency

```python
from fastapi import FastAPI, Depends, status
from pydantic import BaseModel, EmailStr
from fadsync_mailcheck import FastAPIEmailGuard, ValidationResult

app = FastAPI(title="Secured SaaS API")

# Initialize Guard
email_guard = FastAPIEmailGuard(
    api_key="YOUR_FADSYNC_API_KEY",
    block_disposable=True,  # Blocks 40M+ burner domains
    block_dead_mx=True,     # Rejects dead mail domains
)

class SignupRequest(BaseModel):
    name: str
    email: EmailStr
    password: str

@app.post("/api/signup", status_code=status.HTTP_201_CREATED)
async def signup(
    payload: SignupRequest,
    check: ValidationResult = Depends(lambda req: email_guard(req.email)),
):
    # Email is 100% verified, safe, and MX active!
    return {
        "success": True,
        "message": f"Welcome {payload.name}!",
        "risk_score": check.risk_score,
    }
```

---

### 4. Django Form & Model Field Validator

```python
from django.db import models
from fadsync_mailcheck import FadSyncEmailValidator

class UserProfile(models.Model):
    username = models.CharField(max_length=150, unique=True)
    email = models.EmailField(
        unique=True,
        validators=[FadSyncEmailValidator(block_disposable=True)],
    )
```

---

## ⚙️ Configuration Options

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `api_key` | `str` | `os.getenv("FADSYNC_API_KEY")` | Your FadSync API Key |
| `base_url` | `str` | `https://mailcheck.fadsync.com/api/v1` | API base URL |
| `timeout` | `float` | `3.0` | Request timeout in seconds |
| `cache` | `bool \| InMemoryCache` | `True` (300s TTL) | Thread-safe in-memory cache |
| `fail_silent` | `bool` | `True` | Fail-open gracefully on timeouts/errors |

---

## 📊 Result Object Attributes

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `result.email` | `str` | Normalized email address |
| `result.is_disposable` | `bool` | `True` if temporary burner email |
| `result.is_valid_format` | `bool` | `True` if RFC format is valid |
| `result.has_valid_mx` | `bool` | `True` if DNS MX mail server records exist |
| `result.risk_score` | `int` | Fraud risk rating from `0` (clean) to `100` (high risk) |
| `result.typo_fix` | `str \| None` | Suggested domain autocorrection |
| `result.has_typo_suggestion` | `bool` | `True` if typo replacement is available |
| `result.is_safe_to_register` | `bool` | Convenient boolean check for signups |
| `result.user_friendly_message` | `str` | Non-technical explanation ready for UI display |

---

## 📄 License

MIT © [FadSync](https://mailcheck.fadsync.com/)
