Metadata-Version: 2.5
Name: kavikemail
Version: 1.0.0
Summary: Official Python SDK for the Kavik.email email verification API
Project-URL: Homepage, https://kavik.email
Project-URL: Repository, https://github.com/kavik-email/kavik-python
Project-URL: Documentation, https://kavik.email/docs/sdks/
Project-URL: Issues, https://github.com/kavik-email/kavik-python/issues
License-Expression: MIT
License-File: LICENSE
Keywords: api,disposable-email,email,email-validation,email-verification,kavik,kavikemail,sdk,smtp,validation,verification
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.9
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# kavikemail

Official Python SDK for the **Kavik.email** email verification API.

Single dependency (`httpx`). Works with Python 3.9+. Fully typed (`py.typed`).

## Installation

```bash
pip install kavikemail
```

## Quick Start

```python
from kavikemail import Kavik

kavik = Kavik("eva_...")

result = kavik.verify("user@example.com")

print(result.data.score)          # 85
print(result.data.risk)           # "safe"
print(result.data.smtp_check)     # "deliverable"
print(result.data.is_disposable)  # False
print(result.rate_limit.remaining)  # 199
```

## Features

- Single email verification
- Batch verification (up to 100 emails)
- Async bulk file upload (CSV/XLSX) with polling
- Domain deliverability reports (SPF/DKIM/DMARC/blacklists)
- Webhook signature verification (HMAC-SHA256)
- Auto-retry with exponential backoff on 429/5xx (a used-up daily or monthly allowance is not retried)
- Rate limit info on every response
- Full type annotations (PEP 561)

## API Reference

### Constructor

```python
kavik = Kavik(
    api_key="eva_...",                        # Required
    base_url="https://api.kavik.email",         # Default
    timeout=100.0,                            # Seconds (default: 100)
    max_retries=3,                            # Retries on 429/5xx (default: 3)
    retry_delay=1000.0,                       # Base retry delay in ms (default: 1000)
)
```

### Context Manager

```python
with Kavik("eva_...") as kavik:
    result = kavik.verify("user@example.com")
# Client is automatically closed
```

### Single Verification

```python
result = kavik.verify("user@gmail.com")

print(result.data.email)                  # "user@gmail.com"
print(result.data.score)                  # 0-100
print(result.data.risk)                   # "safe" | "risky" | "catchall" | "invalid" | "unknown"
print(result.data.smtp_check)             # "deliverable" | "undeliverable" | "risky" | "unknown"
print(result.data.is_disposable)          # False
print(result.data.is_role_account)        # False
print(result.data.is_catch_all)           # False
print(result.data.is_free_provider)       # True
print(result.data.spam_trap_risk)         # "low" | "medium" | "high"
print(result.data.suggested_correction)   # None or "gmail.com"
print(result.data.mx_records)             # ["aspmx.l.google.com", ...]
```

### Batch Verification

```python
result = kavik.verify_batch([
    "user1@gmail.com",
    "user2@company.com",
    "fake@disposable.xyz",
])

print(result.data.total)  # 3
for r in result.data.results:
    print(r.email, r.risk, r.score)
```

### Bulk File Upload + Polling

```python
# Upload the file
with open("emails.csv", "rb") as f:
    job = kavik.upload_bulk(f, webhook_url="https://myapp.com/webhook/kavik")

print(job.data.id)      # "abc-123"
print(job.data.status)  # "pending"

# Poll until complete
completed = kavik.wait_for_bulk_job(
    job.data.id,
    interval=3.0,   # poll every 3s (default: 5s)
    timeout=300.0,   # max wait 5min (default: 10min)
    on_progress=lambda j: print(f"{j.completed_count}/{j.total_count} processed"),
)

# Download results as typed objects
results = kavik.get_bulk_job_results(completed.data.id)
for r in results.data:
    print(r.email, r.risk, r.score)

# Or download as CSV string
csv_data = kavik.get_bulk_job_results(completed.data.id, format="csv")
with open("results.csv", "w") as f:
    f.write(csv_data)
```

### Domain Deliverability

```python
result = kavik.get_domain_deliverability("example.com")

print(result.data.score)                          # 85
print(result.data.grade)                          # "A"
print(result.data.authentication.spf.found)       # True
print(result.data.authentication.dkim.found)      # True
print(result.data.authentication.dmarc.policy)    # "reject"
print(result.data.blacklist.listed)               # False
```

### Bulk Job Management

```python
# List all jobs
jobs = kavik.list_bulk_jobs()

# Get specific job status
job = kavik.get_bulk_job("job-id-123")
```

## Webhook Verification

Verify incoming webhook signatures without instantiating the client:

```python
from kavikemail import verify_webhook_signature, parse_webhook_event

# Option 1: Verify only
is_valid = verify_webhook_signature(
    payload=raw_body,
    signature=headers["X-EVA-Signature"],
    secret=os.environ["KAVIK_WEBHOOK_SECRET"],
)

# Option 2: Verify + parse in one step
event = parse_webhook_event(
    payload=raw_body,
    signature=headers["X-EVA-Signature"],
    secret=os.environ["KAVIK_WEBHOOK_SECRET"],
)

print(event["job_id"])
print(event["summary"])  # {"safe": 800, "risky": 100, "catchall": 50, "invalid": 50, "unknown": 12}
```

### Flask Example

```python
from flask import Flask, request
from kavikemail import parse_webhook_event, WebhookSignatureError

app = Flask(__name__)

@app.post("/webhook/kavik")
def handle_webhook():
    try:
        event = parse_webhook_event(
            payload=request.get_data(as_text=True),
            signature=request.headers["X-EVA-Signature"],
            secret=os.environ["KAVIK_WEBHOOK_SECRET"],
        )
        print(f"Job {event['job_id']} completed:", event["summary"])
        return "", 200
    except WebhookSignatureError:
        return "Invalid signature", 401
```

## Error Handling

All API errors are raised as typed exceptions:

```python
from kavikemail import (
    Kavik,
    KavikError,
    RateLimitError,
    QuotaExceededError,
    AuthenticationError,
    NotFoundError,
)

kavik = Kavik("eva_...")

try:
    result = kavik.verify("test@example.com")
except RateLimitError as e:
    # Per-minute rate limit hit: wait and retry
    print(f"Rate limited. Retry after {e.retry_after}s")
    print(f"Remaining: {e.rate_limit.remaining}")
except QuotaExceededError:
    # Monthly quota exhausted, no PAYG credits left
    print("Quota exceeded. Purchase credit packs to continue.")
except AuthenticationError:
    # Invalid or missing API key
    print("Check your API key")
except NotFoundError:
    # Resource not found (e.g., invalid bulk job ID)
    print("Not found")
except KavikError as e:
    if e.code == "PAID_PLAN_REQUIRED":
        # Free account without credits: API access needs a plan or a credit
        # pack. Its 300 free checks run in the dashboard.
        print("Pick a plan or a credit pack to use the API.")
    else:
        # Other API error
        print(e.message, e.code, e.status)
```

## Rate Limit Info

Every response includes rate limit data:

```python
result = kavik.verify("user@example.com")

print(result.rate_limit.limit)              # 200 (per-minute limit)
print(result.rate_limit.remaining)          # 199
print(result.rate_limit.reset)              # datetime object (UTC)
print(result.rate_limit.credits_remaining)  # None or int (PAYG credits)
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | none | **Required.** Your Kavik.email API key (starts with `eva_`). |
| `base_url` | `str` | `https://api.kavik.email` | API base URL. |
| `timeout` | `float` | `100.0` | Request timeout (seconds). A check can take up to 90 s when the mail server holds its reply. |
| `max_retries` | `int` | `3` | Max retries on 429/5xx errors. `DAILY_LIMIT` and `QUOTA_EXCEEDED` are never retried. |
| `retry_delay` | `float` | `1000.0` | Base delay (ms) for exponential backoff. |

## Requirements

- Python >= 3.9
- httpx >= 0.27

## Changelog

See [CHANGELOG.md](https://github.com/kavik-email/kavik-python/blob/main/CHANGELOG.md).

## License

MIT
