> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lekalao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clés de test

> Essayer une intégration de bout en bout, webhooks compris, sans envoyer un seul e-mail.

Une clé de test est un jeton d'API qui n'envoie rien. Un e-mail transactionnel envoyé avec elle est vérifié, rendu et journalisé exactement comme un vrai, puis marqué `sent` sans qu'aucun fournisseur n'en entende parler, et compté dans aucun quota. Envoyé à l'une des [adresses puits](#les-adresses-puits), il reçoit aussi la réponse qu'un fournisseur aurait donnée, avec les webhooks qui vont avec.

## Créer une clé de test

**Paramètres → Jetons d'API → Nouveau jeton**, puis activez **Clé de test** avant **Créer**. La liste l'affiche avec un badge **Test**. Une clé est une clé de test dès sa naissance et le reste : pour passer au réel, créez une clé réelle et remplacez-la dans votre configuration.

Votre application peut demander laquelle elle tient :

```bash theme={null}
curl https://api.lekalao.com/v1/me \
  -H "Authorization: Bearer $LEKALAO_TEST_TOKEN" \
  -H "Accept: application/json"
```

```json theme={null}
{ "data": { "team": { "id": "01a0bb7d-…", "name": "Acme" }, "user": { "…": "…" }, "abilities": ["read", "write"], "sandbox": true } }
```

## Ce que change une clé de test

| Appel | Avec une clé de test |
| - | - |
| `POST /v1/transactional-mails/send` | Validé, vérifié contre la liste de suppression et la règle des expéditeurs, rendu et journalisé, puis `sent` avec `"sandbox": true`. Aucun fournisseur, aucun quota consommé. Les webhooks `transactional.*` partent. |
| `POST /v1/transactional-mails/{mail}/resend` | De même. Un e-mail de test renvoyé reste un e-mail de test, quelle que soit la clé. |
| `POST /v1/campaigns/{campaign}/test` | Toutes les vérifications sont faites et la campagne est rendue, puis rien ne part : `"sandbox": true`, rien n'est compté. |
| `POST /v1/campaigns/{campaign}/send`, `POST /v1/automations/{automation}/trigger`, `POST /v1/subscribers/{subscriber}/resend-confirmation` | Refusés, `403` [`sandbox_cannot_send`](https://docs.lekalao.com/fr/errors#sandbox_cannot_send) : ils existent pour écrire à de vraies personnes, ce qui ne se simule pas à moitié. |
| Le [relais SMTP](https://docs.lekalao.com/fr/developers/smtp-relay.md), avec la clé de test pour mot de passe | Chaque message est journalisé comme e-mail de test, et aucun ne part. |
| Tout le reste | Comme une clé réelle. |

> [!WARNING]
>
> Une clé de test lit et écrit les **vraies** listes, abonnés, modèles et
> webhooks de l'équipe. Abonner quelqu'un avec elle peut lui envoyer un vrai
> e-mail de confirmation ou lancer une automatisation. Pour une intégration
> qui crée des contacts pendant que vous l'essayez, utilisez une équipe à
> part : une équipe de test, avec ses propres clés.

Dans le journal, **Transactionnel**, un e-mail de test porte un badge **Test**. `GET /v1/transactional-mails?sandbox=true` ne liste que ceux-là, `?sandbox=false` que les vrais.

## Les adresses puits

Écrivez à ces adresses pour obtenir la réponse d'un fournisseur sans fournisseur. La partie après `+` est libre : `bounced+formulaire@sink.lekalao.dev` est aussi un rebond, pour distinguer plusieurs tests.

| Adresse | Ce qui arrive, un instant après `transactional.sent` |
| - | - |
| `delivered@sink.lekalao.dev` | Délivré : `delivered_at` est rempli, `transactional.delivered` part. |
| `bounced@sink.lekalao.dev` | Un rebond dur : `bounced_at` et `failure_reason` sont remplis, `transactional.bounced` et `mail.bounced` partent. |
| `complained@sink.lekalao.dev` | Délivré, puis signalé comme spam : `transactional.delivered`, `transactional.complained` et `mail.complaint`. |
| `opened@sink.lekalao.dev` | Délivré, puis ouvert : `transactional.opened`, `opens` vaut 1. |
| `clicked@sink.lekalao.dev` | Délivré, ouvert, et son premier lien suivi cliqué : `transactional.clicked` avec l'`url`. |
| `failed@sink.lekalao.dev` | Le fournisseur le refuse : l'appel répond `502` [`provider_error`](https://docs.lekalao.com/fr/errors#provider_error), et `transactional.failed` part. |

Les webhooks sont les vrais, signés, retentés et journalisés comme les autres, avec `"sandbox": true` dans leurs `data`. Un rebond ou une plainte simulés ne mettent **rien** sur la liste de suppression : le même test se rejoue demain.

Toute autre adresse est journalisée et marquée `sent`, et rien de plus ne lui arrive.

> [!NOTE]
>
> Un e-mail écrit **seulement** à des adresses puits n'atteint jamais un
> fournisseur, quelle que soit la clé : il rebondirait sur un domaine qui ne
> reçoit rien, aux dépens du nom de votre expéditeur. Mêlé à de vraies
> adresses, avec une clé réelle, il part comme un autre.

## L'essayer depuis un terminal

Aucune collection à importer, aucun compte ailleurs : `curl` et une clé de test suffisent.

**1. Une clé de test**

Créez-en une comme ci-dessus, puis :

```bash theme={null}
export LEKALAO_TEST_TOKEN="12|kJ3v8mQ2xP9…"
```

**2. Une adresse pour les webhooks**

Celle de votre application, joignable depuis Internet ; sur votre machine, à travers un tunnel comme ngrok ou Cloudflare Tunnel. Enregistrez-la pour les événements transactionnels, et gardez le `secret` de la réponse :

```bash theme={null}
curl -X POST https://api.lekalao.com/v1/webhooks \
  -H "Authorization: Bearer $LEKALAO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "url": "https://votre-tunnel.example/webhooks/lekalao", "events": ["transactional.sent", "transactional.delivered", "transactional.bounced", "transactional.failed"] }'
```

Sautez cette étape pour ne voir les appels que dans **Paramètres → Webhooks sortants** : le journal montre ce qui aurait été envoyé, et sa réponse.

**3. Un e-mail qui rebondit**

```bash theme={null}
curl -X POST https://api.lekalao.com/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "to": ["bounced@sink.lekalao.dev"], "subject": "Votre commande", "html": "<p>Merci !</p>" }'
```

La réponse est `201`, `"status": "sent"`, `"sandbox": true`. Gardez son `id`.

**4. Ce que votre application a reçu**

`transactional.sent`, puis `transactional.bounced` avec `"type": "hard_bounce"` et l'adresse. Vérifiez chaque signature comme le montre [Webhooks](https://docs.lekalao.com/fr/developers/webhooks.md#vérifier-la-signature) : un gestionnaire qui refuse un appel falsifié fait partie du test.

Relisez l'e-mail : `bounced_at` est rempli.

```bash theme={null}
curl https://api.lekalao.com/v1/transactional-mails/$MAIL_ID \
  -H "Authorization: Bearer $LEKALAO_TEST_TOKEN" \
  -H "Accept: application/json"
```

**5. Les autres réponses**

Le même appel vers `delivered@`, `complained@`, `opened@`, `clicked@` et `failed@sink.lekalao.dev` : chacun de vos gestionnaires tourne une fois. Remplacez ensuite la clé de test par une clé réelle.

Pour générer un client plutôt qu'écrire les appels, prenez la description que l'API donne d'elle-même : `GET /v1/openapi.json` (`?lang=fr` pour la française). C'est le même document que la [référence de l'API](https://docs.lekalao.com/fr/api-reference/introduction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.