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:

import os

from kavikemail import verify_webhook_signature, parse_webhook_event

# Option 1: Verify only
is_valid = verify_webhook_signature(
    payload=raw_body,
    signature=headers.get("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.get("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

import os

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.get("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.2

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.2
File Size Uploaded Provenance Actions
kavikemail-1.0.2.tar.gz 17.3 kB With provenance Details for kavikemail-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kavikemail 1.0.2
File Interpreter ABI Platform Actions
kavikemail-1.0.2-py3-none-any.whl Python 3 none any Details for kavikemail-1.0.2-py3-none-any.whl

Total release size: 33.5 kB

Release files / kavikemail-1.0.2.tar.gz

Download URL kavikemail-1.0.2.tar.gz
Size 17.3 kB
Tags Source
SHA-256 checksum
How to use checksums
feff0834999b8907e81847d8d00ef5f3a27beb1dec91f49feb2c03d440d5ba7d
BLAKE2b-256 checksum
How to use checksums
08f285406dbf55fdea373ac1a174d3beb435b419c7be7f72766aaa6bbf2a2a6b
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.2-py3-none-any.whl

Download URL kavikemail-1.0.2-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0f7bfdd1060193bbf7dd01f5cb822c42c0e93261f30f74922d9c8b143efca774
BLAKE2b-256 checksum
How to use checksums
7088e5d3f20d7118e53b4146756a60ee4ca2781aad8f9992f1d1dfc3ccfaa82b
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.2

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