syvel

Official Python SDK for Syvel — disposable email detection API.

Detect throwaway addresses, role accounts, and undeliverable domains before they pollute your database. Works with Python 3.10+, supports both sync and async, and has zero runtime dependencies beyond httpx.

Install

pip install syvel

Quick start

Synchronous

import os
from syvel import Syvel, SyvelError, SyvelTimeoutError

client = Syvel(api_key=os.environ["SYVEL_API_KEY"])

try:
    result = client.check_email("user@example.com")
    if result and result.is_risky:
        print(f"Blocked: {result.reason} (score {result.risk_score})")
    else:
        print("Email looks good")
except SyvelTimeoutError:
    pass  # Always fail open on timeouts
except SyvelError as e:
    print(f"API error {e.status_code}: {e}")

Asynchronous

import os
from syvel import AsyncSyvel

async def validate(email: str) -> bool:
    async with AsyncSyvel(api_key=os.environ["SYVEL_API_KEY"]) as client:
        result = await client.check_email(email)
        return result is None or not result.is_risky

Fail-open (silent) mode

When you'd rather accept every user than block one legitimate signup, use silent=True. All errors are suppressed and methods return None:

client = Syvel(api_key=os.environ["SYVEL_API_KEY"], silent=True)

result = client.check_email("user@example.com")
# Returns None on any error — never blocks your signup flow
if result and result.is_risky:
    print("Risky email detected")

Configuration

API reference

check(domain)

Check a bare domain for disposable-email risk.

result = client.check("yopmail.com")

check_email(email)

Check a full email address. Passes the complete address to the API to enable local-part analysis (role account detection, random pattern scoring).

result = client.check_email("admin@example.com")

usage()

Get the current monthly quota and usage for your project.

usage = client.usage()
print(f"{usage.used}/{usage.limit} checks used this month")

logs(cursor=None, limit=None)

Retrieve a paginated page of recent request logs.

page = client.logs(limit=50)
for entry in page.items:
    print(entry.target, entry.risk_score)

# Fetch next page
if page.next_cursor:
    next_page = client.logs(cursor=page.next_cursor, limit=50)

stats()

Retrieve time-series analytics for the last 30 days.

points = client.stats()
for point in points:
    print(f"{point.date}: {point.total} checks, {point.risky} risky")

list_keys() / create_key(name) / revoke_key(key_id)

Manage API keys for your project.

keys = client.list_keys()

new_key = client.create_key("Staging")
print(new_key.id)

client.revoke_key(new_key.id)

All methods are available on AsyncSyvel as coroutines — prefix them with await.

Response fields

Error handling

All errors inherit from SyvelError. Catch specific subclasses for fine-grained handling:

from syvel import (
    SyvelError,
    SyvelAuthError,
    SyvelForbiddenError,
    SyvelValidationError,
    SyvelRateLimitError,
    SyvelTimeoutError,
)

try:
    result = client.check_email("user@example.com")
except SyvelAuthError:
    # Invalid or missing API key
    print("Check your SYVEL_API_KEY")
except SyvelRateLimitError as e:
    # Monthly quota exceeded
    print(f"Quota resets at {e.reset_at}")
except SyvelTimeoutError:
    # Request took longer than `timeout` seconds
    pass  # Always fail open
except SyvelValidationError:
    # Invalid email or domain format
    pass
except SyvelForbiddenError:
    # Origin not whitelisted for this API key
    pass
except SyvelError as e:
    # Catch-all for unexpected API errors
    print(f"Syvel error {e.status_code}: {e}")

Framework examples

Django

# validators.py
import os
from django.core.exceptions import ValidationError
from syvel import Syvel

_client = Syvel(api_key=os.environ["SYVEL_API_KEY"], silent=True)

def validate_not_disposable(value: str) -> None:
    result = _client.check_email(value)
    if result and result.is_risky:
        raise ValidationError(
            "Please use a permanent email address.",
            code="disposable_email",
        )

# forms.py
from django import forms
from .validators import validate_not_disposable

class SignupForm(forms.Form):
    email = forms.EmailField(validators=[validate_not_disposable])

FastAPI

import os
from functools import lru_cache
from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException
from syvel import AsyncSyvel, CheckResult

app = FastAPI()

@lru_cache(maxsize=1)
def get_client() -> AsyncSyvel:
    return AsyncSyvel(api_key=os.environ["SYVEL_API_KEY"], silent=True)

async def email_risk(
    email: str,
    client: AsyncSyvel = Depends(get_client),
) -> CheckResult | None:
    return await client.check_email(email)

EmailRisk = Annotated[CheckResult | None, Depends(email_risk)]

@app.post("/signup")
async def signup(email: str, risk: EmailRisk):
    if risk and risk.is_risky:
        raise HTTPException(422, f"Disposable email not allowed ({risk.reason})")
    return {"status": "ok"}

Flask

import os
from flask import Flask, abort, request
from syvel import Syvel

app = Flask(__name__)
_client = Syvel(api_key=os.environ["SYVEL_API_KEY"], silent=True)

@app.before_request
def check_email():
    if request.endpoint == "register" and request.method == "POST":
        email = request.form.get("email", "")
        result = _client.check_email(email)
        if result and result.is_risky:
            abort(422, "Disposable email addresses are not allowed.")

Context manager

Use Syvel or AsyncSyvel as a context manager to ensure connections are released when you're done:

# Sync
with Syvel(api_key="sv_...") as client:
    result = client.check("yopmail.com")

# Async
async with AsyncSyvel(api_key="sv_...") as client:
    result = await client.check("yopmail.com")

For long-lived processes (web servers), create the client once at startup and call client.close() / await client.aclose() on shutdown instead.

Contributing

Pull requests are welcome. For major changes, please open an issue first.

git clone https://github.com/syvel-io/syvel-python.git
cd syvel-python
pip install -e ".[dev]"

# Run tests
pytest

# Lint + type-check
ruff check src tests
mypy src

License

MIT