kavikemail
Official Python SDK for the Kavik.email email verification API.
Single dependency (httpx). Works with Python 3.9+. Fully typed (py.typed).
Installation
pip install kavikemail
Quick Start
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
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
with Kavik("eva_...") as kavik:
result = kavik.verify("user@example.com")
# Client is automatically closed
Single Verification
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
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
# 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
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
# 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:
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
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:
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:
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.
License
MIT
Metadata
Release files for kavikemail 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kavikemail-1.0.0.tar.gz | 17.1 kB | With provenance | Details for kavikemail-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kavikemail-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for kavikemail-1.0.0-py3-none-any.whl |
Total release size: 33.4 kB
Release files / kavikemail-1.0.0.tar.gz
| Download URL | kavikemail-1.0.0.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9b225758d53fe26b167528e78c9ec30401bdc79b06eed8c2a5dbb06398ba7b2
|
|
BLAKE2b-256 checksum How to use checksums |
318e6477e0142220546deb982f6e84eb9c16265e982dfe80edc104561993ca8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / kavikemail-1.0.0-py3-none-any.whl
| Download URL | kavikemail-1.0.0-py3-none-any.whl |
|---|---|
| Size | 16.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5889632f03f11f5b16cd50991ada9c49ab28580c54070b3b740288c82698346
|
|
BLAKE2b-256 checksum How to use checksums |
15f139cbc7f5d50ff5ef8dfd70c235d655996476e47edefd94f2ce8f299e4645
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for kavikemail 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kavikemail-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.