# Démarrage

Du compte au premier email remis. Comptez cinq minutes, plus le temps de propagation
DNS, qui ne dépend pas de nous.

## 1. Une clé d'API

Elle se crée depuis le tableau de bord VaEmail, rubrique « Clés API ». C'est une étape
humaine : il n'y a pas d'endpoint de création de compte, et un agent ne peut pas s'en
procurer une tout seul.

Une clé destinée à un agent gagne à être bornée dès sa création : portées limitées à ce
dont il a besoin, plafond d'envois par jour, et liste des domaines expéditeurs autorisés.
Voir [Sécurité](security.md).

```
export VAEMAIL_API_KEY=swm_votre_cle
```

## 2. Vérifier que tout répond

```
npx vaemail init
```

La commande dit, dans l'ordre : si le service répond, si la clé est acceptée, et si un
domaine d'envoi est authentifié. Elle affiche aussi la configuration MCP à coller.

Sans installer quoi que ce soit :

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

Cet appel ne demande pas de clé. Il décrit ce que le service sait faire, ses limites et
ses portées.

## 3. Déclarer un domaine d'envoi

Envoyer depuis un domaine non authentifié, c'est envoyer dans les indésirables. Les
grands fournisseurs de messagerie vérifient SPF et DMARC avant de décider où poser le
message.

```
npx vaemail domains:add exemple.fr
```

La réponse contient les enregistrements DNS à publier, avec le rôle de chacun. Un
enregistrement marqué `publishable: false` contient encore une valeur qui dépend de la
configuration du serveur d'envoi : la publier telle quelle casserait l'authentification.
Demandez-la avant de poser cet enregistrement.

Publier les enregistrements se fait chez votre registrar. C'est une étape humaine.

Une fois publiés, comptez de quelques minutes à quelques heures, puis :

```
npx vaemail domains
```

## 4. Un essai à blanc

Avant le premier vrai message :

```
curl -X POST https://app.vaemail.fr/api/v1/messages/validate \
  -H "api-key: $VAEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"client@exemple.fr","html":"<p>Bonjour</p>"}'
```

La réponse dit si l'envoi passerait (`sendable`) et, sinon, ce qui le bloque, avec les
mêmes codes que les erreurs d'envoi. Rien n'est envoyé.

## 5. Envoyer

```
curl -X POST https://app.vaemail.fr/api/v1/transactional/send \
  -H "api-key: $VAEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facture-2412" \
  -d '{"to":"client@exemple.fr","subject":"Votre facture","html":"<p>Bonjour</p>"}'
```

Réponse :

```json
{ "success": true, "data": { "id": 2841, "status": "queued" } }
```

Le 202 dit que le message est accepté et mis en file. Il ne dit pas qu'il est arrivé.

L'en-tête `Idempotency-Key` est facultatif mais fortement recommandé dès qu'un programme
appelle : si la réponse se perd et que l'appel est relancé, la première réponse est
rejouée au lieu d'envoyer un deuxième message.

## 6. Savoir ce qu'il est devenu

```
curl https://app.vaemail.fr/api/v1/messages/2841 \
  -H "api-key: $VAEMAIL_API_KEY"
```

`status` passe par `queued`, puis `sent`, puis `delivered` quand le fournisseur du
destinataire confirme la remise. En cas d'échec, `error` porte le motif renvoyé par le
transport, et `events` la suite de ce qui s'est passé.

C'est ce seul appel qui autorise à dire qu'un email est arrivé.

## Ensuite

- [Serveur MCP](mcp.md), pour brancher un agent conversationnel
- [Référence de l'API](api.md), tous les endpoints
- [Codes d'erreur](errors.md), et quoi faire pour chacun
- [Délivrabilité](deliverability.md), quand le courrier arrive mal