Metadata-Version: 2.4
Name: emailprobe-sdk
Version: 0.1.1
Summary: Official Python SDK for the EmailProbe disposable email detection API
Author-email: EmailProbe <support@emailprobe.dev>
License: MIT
Project-URL: Homepage, https://emailprobe.dev
Project-URL: Documentation, https://app.emailprobe.dev/docs.html
Project-URL: Repository, https://emailprobe.dev
Keywords: email,validation,disposable,temporary,detection,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == "async"
Dynamic: license-file

# emailprobe-sdk

Official Python SDK for the [EmailProbe](https://emailprobe.dev) disposable email detection API.

## Install

```bash
pip install emailprobe-sdk
```

For async support:
```bash
pip install emailprobe-sdk[async]
```

## Quick Start

```python
from emailprobe import EmailProbeClient

client = EmailProbeClient(api_key="ep_live_your_api_key")

# Validate an email
result = client.validate("user@tempmail.com")
print(result["is_disposable"])  # True
print(result["verdict"])        # "disposable"
print(result["score"])          # 95

# Check a domain only
domain = client.check_domain("mailinator.com")
print(domain["is_disposable"])  # True

# Get usage stats
usage = client.usage()
print(f"{usage['used']}/{usage['monthly_limit']} used")

# Free API — no key needed
check = client.is_disposable("guerrillamail.com")
print(check["disposable"])  # True
```

## Async Usage

```python
from emailprobe.client import AsyncEmailProbeClient

async with AsyncEmailProbeClient(api_key="ep_live_your_api_key") as client:
    result = await client.validate("user@tempmail.com")
    print(result["is_disposable"])
```

Requires `httpx`: `pip install emailprobe-sdk[async]`

## API Reference

### `EmailProbeClient(api_key, base_url=None, timeout=10)`

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | `str` | *required* | Your API key from [app.emailprobe.dev](https://app.emailprobe.dev) |
| `base_url` | `str` | `https://api.emailprobe.dev` | API base URL |
| `timeout` | `int` | `10` | Request timeout in seconds |

### Methods

#### `validate(email: str) -> dict`
Full email validation with disposable detection, MX records, DNS auth, and scoring.

#### `check_domain(domain: str) -> dict`
Domain-only check. Faster — skips local part analysis.

#### `usage() -> dict`
Returns your current plan, usage count, and remaining quota.

#### `is_disposable(domain: str) -> dict`
Free open API. Checks if a domain is disposable. No API key required.

### Error Handling

```python
from emailprobe import EmailProbeClient, RateLimitError, AuthenticationError

client = EmailProbeClient(api_key="ep_live_your_api_key")

try:
    result = client.validate("test@example.com")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
```

## Requirements

- Python 3.8+
- No dependencies (uses `urllib`)
- Optional: `httpx` for async support

## License

MIT
