:::note[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

```bash
pip install syvel
```

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

## Démarrage rapide

```python
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

```python
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

```python
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)

```python
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

```python
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.

```python
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](https://pypi.org/project/syvel/)
- [GitHub — syvel-python](https://github.com/Syvel-io/syvel-python)
- [Python (httpx / requests) — sans dépendance SDK](/fr/docs/integrations/python-httpx)
- [Référence API — Vérification email](/fr/docs/api/check)
- [Authentification](/fr/docs/guides/authentication)
- [Codes d'erreur](/fr/docs/guides/errors)