Metadata-Version: 2.4
Name: mailveri
Version: 1.0.0
Summary: Official zero-dependency Python SDK (sync & async) for MailVeri email verification ($59/100K, $299/1M, non-expiring credits).
Author-email: MailVeri <support@mailveri.com>
License: MIT
Project-URL: Homepage, https://mailveri.com
Project-URL: Documentation, https://mailveri.com/docs
Project-URL: Issues, https://mailveri.com/contact
Keywords: mailveri,email-verification,email-validation,deliverability,catch-all,disposable-email,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MailVeri Python SDK (`mailveri`)

Official zero-dependency Python SDK (sync & async) for the [MailVeri](https://mailveri.com) email verification API. Runs on Python `>=3.10` with standard library only — ideal for Windmill, Google Colab, Jupyter, FastAPI, and ETL scripts.

- **Transparent PAYG Pricing:** `$9 / 10K` (`$0.0009/check`), `$39 / 60K`, `$59 / 100K`, `$299 / 1M` (`$0.0003/check`), up to `$999 / 5M` (`$0.0002/check`) — non-expiring credits.
- **No charge for `UNKNOWN`:** Unverifiable addresses cost `0` credits.

## Installation

```bash
pip install mailveri
```

## Quick Start (Sync & Async)

Set `MAILVERI_API_KEY` from [app.mailveri.com/api-keys/](https://app.mailveri.com/api-keys/) (or pass it explicitly):

```python
from mailveri import MailVeri

client = MailVeri()

# 1. Real-time verification
res = client.verify("user@example.com")
print(res["status"], res["is_deliverable"], res["credits_used"])

# 2. Check credit balance
bal = client.get_balance()
print("Available credits:", bal["available_credits"])

# 3. Bulk batch verification (2 to 100,000 unique emails)
batch = client.submit_batch(["user@example.com", "name@company.com"], filename="leads.csv")
status = client.get_batch_status(batch["job_id"])
if status["is_finished"]:
    # Omit `status` to default to `VALID,ROLE_ACCOUNT`; pass e.g. `status="INVALID,DISPOSABLE"` for suppressions.
    csv_text = client.download_batch_csv(batch["job_id"], status="VALID,ROLE_ACCOUNT", columns="compact")
    print(csv_text)
    suppression_csv = client.download_batch_csv(batch["job_id"], status="INVALID,DISPOSABLE")
    print(suppression_csv)
```

Async usage (`AsyncMailVeri`):

```python
import asyncio
from mailveri import AsyncMailVeri

async def main() -> None:
    client = AsyncMailVeri()
    res = await client.verify("user@example.com")
    print(res)

asyncio.run(main())
```

## Verification Statuses

- `VALID` — Mailbox exists and can receive mail (`is_valid=True`, `is_deliverable=True`)
- `ROLE_ACCOUNT` — Shared role address such as `info@` or `support@` (`is_deliverable=True`)
- `INVALID` — Undeliverable or invalid syntax (`is_deliverable=False`)
- `DISPOSABLE` — Temporary burner mailbox (`is_deliverable=False`)
- `CATCH_ALL` — Domain accepts any recipient address (`is_deliverable=False`)
- `FULL_INBOX` — Mailbox quota exceeded (`is_deliverable=False`)
- `UNKNOWN` — Temporary inability to verify (`0` credits charged)

## License & Support

MIT — Support: `support@mailveri.com` · Docs: https://mailveri.com/docs · Pricing: https://mailveri.com/pricing
