Skip to main content

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)

Source distribution for kavikemail 1.0.0
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)

Table of built distributions (wheels) for kavikemail 1.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page