# Démarrage avec Python

Ce guide utilise le paquet `vaemail` du SDK Python. Il n’a aucune dépendance externe et utilise `urllib`.

## Prérequis

- Python compatible avec le SDK.
- `pip`.
- Une clé d’API et un domaine d’envoi authentifié.

```bash
python3 -m pip install vaemail
export VAEMAIL_API_KEY="<votre clé de test>"
```

## Tutoriel

```python
import os
from vaemail import VaEmail

client = VaEmail(api_key=os.environ['VAEMAIL_API_KEY'])
message = {
    'to': 'client@example.com',
    'subject': 'Votre commande',
    'html': '<p>Votre commande est confirmée.</p>',
}

contrôle = client.validate(message)
if contrôle.get('sendable') is False:
    raise RuntimeError(contrôle)

accepte = client.send(message, idempotency_key='commande-4711')
print(accepte)
print(client.get_message(accepte['data']['id']))
```

Le SDK expose aussi `diagnose_deliverability`, `dns_records`, `usage` et `audit_logs`. La clé d’idempotence rend une relance sûre pendant 24 heures.

## Comment tester

```bash
curl https://app.vaemail.fr/api/v1/capabilities
```

Le test réel consiste à lire `get_message` après l’envoi. Seul `delivered` permet d’affirmer que le message est remis.

## Limites

Le SDK ne crée pas de compte, ne publie pas les DNS et ne contient pas de client PHP. Les erreurs sont levées comme `VaEmailError`, avec `code`, `status`, `retryable` et `for_agent()`.

## Reprise après erreur

Si `VaEmailError.retryable` vaut vrai, respecte la résolution renvoyée. Après un délai ou une réponse perdue sur un envoi, relance avec la même clé `commande-4711`, puis lis le message avant toute nouvelle tentative.