Metadata-Version: 2.4
Name: mailodds
Version: 0.2.0
Summary: MailOdds Email Validation API - SDK and CLI
Home-page: 
Author: MailOdds Support
Author-email: MailOdds <support@mailodds.com>
License: MIT
Project-URL: Homepage, https://mailodds.com
Project-URL: Documentation, https://mailodds.com/docs
Project-URL: Repository, https://github.com/mailodds/python-sdk
Keywords: email,validation,verification,mailodds,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: sseclient-py>=1.7
Requires-Dist: rich>=13.0
Dynamic: author

# MailOdds SDK for Python

Enterprise-ready Python client for the [MailOdds Email Validation API](https://mailodds.com/docs).

## Installation

```bash
pip install mailodds
```

## Quick Start

```python
import mailodds
from mailodds.api import EmailValidationApi
from mailodds.models import ValidateRequest

config = mailodds.Configuration(access_token="mo_live_your_api_key")

with mailodds.ApiClient(config) as client:
    api = EmailValidationApi(client)
    result = api.validate_email(ValidateRequest(email="user@example.com"))

    # Branch on action for decisioning
    match result.action:
        case "accept":
            print("Safe to send")
        case "accept_with_caution":
            print("Valid but risky -- flag for review")
        case "reject":
            print("Do not send")
        case "retry_later":
            print("Temporary failure -- retry after backoff")
```

## Enterprise Features

This SDK includes enterprise-ready features beyond the generated API client:

### Built-in Retry (429/5xx)

```python
from mailodds.enterprise import RetryConfig, retry_api_client

config = mailodds.Configuration(access_token="mo_live_your_api_key")

with mailodds.ApiClient(config) as client:
    retry_api_client(client, RetryConfig(max_retries=3, base_delay=1.0))
    api = EmailValidationApi(client)
    # Automatically retries on 429/5xx with exponential backoff
    result = api.validate_email(ValidateRequest(email="user@example.com"))
```

### Typed Errors

```python
from mailodds.enterprise import MailOddsError, InsufficientCreditsError
from mailodds.exceptions import ApiException

try:
    result = api.validate_email(request)
except ApiException as e:
    error = MailOddsError.from_exception(e)
    if isinstance(error, InsufficientCreditsError):
        print(f"Need {error.credits_needed} credits, have {error.credits_available}")
        print(f"Upgrade: {error.upgrade_url}")
```

### Webhook Signature Verification

```python
from mailodds.enterprise import WebhookVerifier

verifier = WebhookVerifier("your_webhook_secret")

payload = request.get_data(as_text=True)
signature = request.headers.get("X-MailOdds-Signature", "")

event = verifier.verify_and_parse(payload, signature)
print(f"Event: {event['event']}")
print(f"Job ID: {event['job']['id']}")
```

## Response Handling

Branch on the `action` field for decisioning:

| Action | Meaning | Recommended |
|--------|---------|-------------|
| `accept` | Safe to send | Add to mailing list |
| `accept_with_caution` | Valid but risky (catch-all, role account) | Flag for review |
| `reject` | Invalid or disposable | Do not send |
| `retry_later` | Temporary failure | Retry after backoff |

## Test Mode

Use an `mo_test_` prefixed API key with test domains for predictable responses without consuming credits.

## API Reference

- Full documentation: https://mailodds.com/docs
- OpenAPI spec: https://mailodds.com/openapi.yaml

## License

MIT
