SDK Python

Fail-open par défaut

Chaque exemple retourne None si l’API est injoignable. Laissez toujours l’utilisateur passer quand Syvel est indisponible — ne bloquez jamais une inscription à cause d’un service tiers.

Installation

pip install syvel

Requires Python 3.10+. Aucune dépendance runtime au-delà de httpx.

Démarrage rapide

import os
from syvel import Syvel

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

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

if result and result.is_risky:
    raise ValueError("Veuillez utiliser une adresse email professionnelle.")
# result est None → Syvel indisponible, laisser passer l'utilisateur

Utilisation asynchrone

import os
from syvel import AsyncSyvel

async def validate_email(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

Django REST Framework

from rest_framework import serializers
import os
from syvel import Syvel

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


class RegisterSerializer(serializers.Serializer):
    email = serializers.EmailField()

    def validate_email(self, value):
        result = client.check_email(value)
        if result and result.is_risky:
            raise serializers.ValidationError(
                "Veuillez utiliser une adresse email professionnelle."
            )
        return value

FastAPI (async)

from fastapi import FastAPI, HTTPException
import os
from syvel import AsyncSyvel

app = FastAPI()


@app.post("/register")
async def register(email: str):
    async with AsyncSyvel(api_key=os.environ["SYVEL_API_KEY"]) as client:
        result = await client.check_email(email)
    if result and result.is_risky:
        raise HTTPException(
            status_code=422,
            detail="Veuillez utiliser une adresse email professionnelle.",
        )
    # continuer l'inscription…

Flask

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

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


@app.route("/register", methods=["POST"])
def register():
    email = request.json.get("email")
    result = client.check_email(email)
    if result and result.is_risky:
        return jsonify({"error": "Veuillez utiliser une adresse email professionnelle."}), 422
    # continuer l'inscription…

Champs de la réponse

Champ	Type	Description
is_risky	bool	True si l’email est à risque
risk_score	int	Score de risque (0–100)
reason	str	"safe" | "disposable" | "undeliverable" | "role_account"
deliverability_score	int	Probabilité de délivrabilité (0–100)
did_you_mean	str | None	Suggestion de correction de frappe
is_free_provider	bool	Gmail, Yahoo, etc.
is_corporate_email	bool	Domaine professionnel détecté
is_alias_email	bool	Service de relais de confidentialité (ex : iCloud Hide My Email)

Gestion des erreurs

Par défaut, le SDK lève des exceptions en cas d’erreur. Passez silent=True pour retourner None à la place.

from syvel import Syvel, SyvelAuthError, SyvelRateLimitError, SyvelError

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

try:
    result = client.check_email("user@example.com")
except SyvelAuthError:
    pass  # clé API invalide
except SyvelRateLimitError:
    pass  # quota dépassé
except SyvelError:
    pass  # toute autre erreur Syvel → fail open

Configuration

Paramètre	Défaut	Description
api_key	—	Votre clé API (depuis syvel.io/dashboard)
base_url	https://api.syvel.io	URL de base de l’API
timeout	3.0	Timeout en secondes
silent	False	Retourne None au lieu de lever une exception

Ressources

• PyPI — syvel
• GitHub — syvel-python
• Python (httpx / requests) — sans dépendance SDK
• Référence API — Vérification email
• Authentification
• Codes d’erreur