Metadata-Version: 2.4
Name: emailintel
Version: 0.1.0
Summary: Official Python SDK for the Email Deliverability Intelligence API
Project-URL: Homepage, https://emailintel.dev
Project-URL: Documentation, https://docs.emailintel.dev
Project-URL: Repository, https://github.com/email-deliverability-intelligence/python-sdk
Author-email: Jonathon Tamm <j.tamm@dynamics-group.com>
License-Expression: MIT
Keywords: catch-all,deliverability,domain-intelligence,email,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# Email Deliverability Intelligence - Python SDK

Official Python SDK for the [Email Deliverability Intelligence API](https://emailintel.dev). Verify emails, analyze domain health, predict deliverability, and more -- all without sending test emails.

## Installation

```bash
pip install emailintel
```

## Quick Start

### Synchronous

```python
from emailintel import EmailIntelClient

client = EmailIntelClient(api_key="edi_live_your_key_here")

# Verify an email
result = client.verify_email("john@example.com", deep_scan=True)
print(f"Result: {result.result}, Confidence: {result.confidence}")

# Get domain intelligence
intel = client.get_domain_intelligence("example.com")
print(f"Provider: {intel.provider}, Risk: {intel.risk_level}")

# Find someone's email
found = client.find_email("example.com", "John", "Doe")
print(f"Email: {found.email}, Confidence: {found.confidence}")

client.close()
```

### Asynchronous

```python
import asyncio
from emailintel import AsyncEmailIntelClient

async def main():
    async with AsyncEmailIntelClient(api_key="edi_live_your_key_here") as client:
        result = await client.verify_email("john@example.com")
        print(f"Result: {result.result}, Confidence: {result.confidence}")

asyncio.run(main())
```

### Context Manager

```python
from emailintel import EmailIntelClient

with EmailIntelClient(api_key="edi_live_your_key_here") as client:
    result = client.verify_email("john@example.com")
```

## Available Methods

### Email Verification

- `verify_email(email, deep_scan=False, include_signals=False)` -- Verify a single email
- `verify_batch(emails, webhook_url=None)` -- Submit batch verification
- `get_batch_status(job_id)` -- Check batch job status

### Domain Intelligence

- `get_domain_intelligence(domain)` -- Full domain intelligence
- `get_domain_pattern(domain)` -- Email naming pattern detection
- `get_domain_compliance(domain)` -- Bulk sender compliance check
- `get_domain_blacklist(domain, refresh=False)` -- DNSBL blacklist check
- `get_domain_report(domain, format="json")` -- Comprehensive domain report
- `compare_domains(domains)` -- Compare 2-5 domains side-by-side
- `get_domain_reputation(domain)` -- Sender reputation score (0-100)
- `get_reputation_history(domain, limit=30)` -- Reputation score timeline
- `get_domain_advisor(domain)` -- AI infrastructure recommendations

### Email Finder

- `find_email(domain, first_name, last_name)` -- Predict email address

### Content Analysis

- `analyze_content(subject, body, sender_domain)` -- Spam risk analysis

### Predictions

- `predict_engagement(email, content_snippet=None)` -- Engagement likelihood
- `predict_deliverability(sender_domain, recipient_email)` -- Inbox placement prediction

### Domain Monitoring

- `register_monitored_domains(domains, webhook_url, interval_seconds=21600)` -- Register monitoring
- `list_monitored_domains()` -- List monitored domains
- `unregister_monitored_domain(domain)` -- Remove monitoring

### Postmaster Tools

- `get_postmaster_data(domain)` -- Combined Google + Microsoft data
- `sync_postmaster_data(domain)` -- Trigger manual data sync

## Error Handling

The SDK throws typed exceptions for different error conditions:

```python
from emailintel import (
    EmailIntelClient,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
    ValidationError,
    NotFoundError,
    ServerError,
)

client = EmailIntelClient(api_key="edi_live_your_key_here")

try:
    result = client.verify_email("john@example.com")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except InsufficientCreditsError:
    print("No credits remaining")
except ValidationError as e:
    print(f"Bad request: {e.details}")
except ServerError:
    print("Server error - will auto-retry")
```

## Configuration

```python
client = EmailIntelClient(
    api_key="edi_live_your_key_here",
    base_url="https://api.emailintel.dev",  # Custom base URL
    max_retries=3,                           # Retry transient failures
    timeout=30.0,                            # Request timeout in seconds
)
```

## Auto-Retry

The SDK automatically retries on transient failures:

- **429 (Rate Limited)**: Respects `retry_after` from the response
- **5xx (Server Errors)**: Exponential backoff with jitter
- **400, 401, 402, 404**: Never retried (client errors)

## Requirements

- Python 3.9+
- httpx >= 0.25.0
- pydantic >= 2.0.0

## License

MIT
