# Brancher VaEmail à un agent

Cette page s'adresse à un agent de code (Claude Code, Codex, Cursor, un agent MCP) ou à
la personne qui le pilote. Elle dit ce qu'un agent peut faire seul, ce qui reste une
étape humaine, et dans quel ordre s'y prendre.

## À copier dans votre agent de code

```
Intègre VaEmail à ce projet comme fournisseur d'email sortant.
Documentation officielle pour agents : https://vaemail.fr/llms.txt
Spécification OpenAPI : https://app.vaemail.fr/openapi.json
Ce que le service sait faire, sans clé : https://app.vaemail.fr/api/v1/capabilities

Règles :
- La clé d'API est dans la variable d'environnement VAEMAIL_API_KEY. Ne la demande pas,
  ne l'écris jamais dans un fichier versionné.
- Avant tout envoi réel, appelle POST /api/v1/messages/validate et arrête-toi si
  « sendable » vaut false.
- Mets un en-tête Idempotency-Key sur chaque envoi, dérivé de l'action métier.
- Un 202 signifie « accepté », pas « remis » : lis GET /api/v1/messages/{id} avant
  d'annoncer une remise.
- Publier des enregistrements DNS, créer un compte ou payer sont des étapes humaines :
  signale-les, ne les déclare jamais faites.
```

## Ce qu'un agent peut faire seul

| Étape | Comment |
| --- | --- |
| Découvrir le service | `GET /api/v1/capabilities`, sans clé |
| Vérifier sa clé et l'état du compte | `npx vaemail init` ou `GET /api/v1/usage` |
| Déclarer un domaine d'envoi | `POST /api/v1/domains` |
| Obtenir les enregistrements DNS à publier | `GET /api/v1/domains/{domaine}/dns` |
| Vérifier qu'un domaine est authentifié | `POST /api/v1/domains/verify` |
| Savoir si un envoi passerait | `POST /api/v1/messages/validate` |
| Envoyer | `POST /api/v1/transactional/send` avec `Idempotency-Key` |
| Suivre la remise | `GET /api/v1/messages/{id}` |
| Comprendre une erreur | le bloc `error` : `code`, `resolution`, `retryable`, `documentation` |
| Diagnostiquer une mauvaise délivrabilité | `GET /api/v1/deliverability/diagnose?domain=` |
| Savoir ce qu'il lui reste | `GET /api/v1/usage` |
| Rendre compte de ce qu'il a fait | `GET /api/v1/audit-logs` |

Les treize outils du [serveur MCP](mcp.md) couvrent les mêmes étapes.

## Ce qui reste humain

- **Créer le compte et la clé d'API.** Il n'y a pas d'endpoint d'inscription. La clé se
  crée depuis le tableau de bord, et c'est là qu'on la borne (voir ci-dessous).
- **Publier les enregistrements DNS** chez le registrar. L'API rend les valeurs, pas
  l'accès à la zone. Un enregistrement marqué `publishable: false` attend encore une
  valeur : le poser tel quel casserait l'authentification.
- **Payer** un abonnement ou relever un quota.
- **Expédier une campagne à toute une liste.** `POST /v3/emailCampaigns/{id}/sendNow`
  exige une confirmation explicite dans le corps de la requête : il ne se lance pas par
  accident.

## Une clé pour un agent

Créer une clé dédiée, nommée d'après l'agent, et la borner à la création :

- portées : `email.send` et `email.read_status` suffisent pour envoyer et suivre ;
  ajouter `domain.read` et `domain.write` si l'agent configure le domaine ;
- `max_emails_per_day` : le volume que l'agent est censé produire, pas plus ;
- `max_recipients_per_email` : 1 pour du transactionnel ;
- `allowed_domains` : le seul domaine expéditeur prévu.

Le [journal](security.md#journal) rend ensuite lisible tout ce que cette clé a fait, et
la révoquer n'arrête rien d'autre.

## Ce que VaEmail ne fait pas

- Pas de boîte de réception créée à la volée : un agent ne peut pas obtenir une adresse
  pour recevoir un code de vérification ou une réponse. La réception existe pour les
  séquences de prospection (`/v3/outreach/inbox`), rattachée à une boîte IMAP déclarée.
- Pas de coût par message dans l'API : les plafonds se posent en nombre d'emails, pas
  en euros.
- Pas d'inscription par API.

## Où sont les choses

- Index pour les modèles de langage : https://vaemail.fr/llms.txt
- Toute la documentation en un fichier : https://vaemail.fr/llms-full.txt
- Spécification OpenAPI 3.1 : https://app.vaemail.fr/openapi.json
- Capacités du service : https://app.vaemail.fr/api/v1/capabilities
- Codes d'erreur : https://vaemail.fr/docs/errors.md
- Serveur MCP et ligne de commande : https://vaemail.fr/docs/mcp.md