# Déclencher un workflow depuis ton application

Un workflow peut démarrer quand ton application le lui demande. Quand une commande est payée, ton site envoie un événement : le contact est créé s’il n’existe pas, puis il entre dans le workflow qui attend cet événement.

**Avant de commencer** : une clé d’API pour ton application (voir [Envoyer depuis ton logiciel](/docs/guides/envoyer-depuis-ton-logiciel/)), et un workflow actif dont le déclencheur est **Ton application envoie un événement**.

1. **Choisis le nom de l'événement**

   Dans le workflow, sur la carte **Déclencheur**, tape un nom comme « Commande payée ». Il devient `commande_payee` : minuscules, sans accents, espaces remplacés par `_`. Tu peux aussi écrire directement le nom technique, avec des lettres minuscules, des chiffres, `.`, `_` ou `-`.

2. **Active le workflow**

   Un workflow qui attend un événement s’active comme les autres. À l’activation, il ne touche pas aux contacts déjà présents : seuls les événements reçus après l’activation le font entrer.

3. **Envoie l'événement depuis ton application**

   Au moment voulu, ton application appelle l’API avec le nom et l’adresse du contact. Le contact est créé ou complété, puis il entre dans le workflow.

## Envoyer l’événement

```bash
curl -X POST https://api.mail.hgdc.ch/events \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "commande_payee",
    "email": "client@exemple.ch",
    "first_name": "Léa",
    "properties": { "montant": 129.9 }
  }'
```

```ts
const response = await fetch("https://api.mail.hgdc.ch/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "commande_payee",
    email: "client@exemple.ch",
    first_name: "Léa",
    properties: { montant: 129.9 },
  }),
})
const result = await response.json()
```

```ts
import { Agentmail } from "./lib/agentmail"

const mail = new Agentmail()
const result = await mail.events.send({
  name: "commande_payee",
  email: "client@exemple.ch",
  first_name: "Léa",
  properties: { montant: 129.9 },
})
```

La réponse dit ce qui s’est passé :

```json
{
  "object": "event",
  "name": "commande_payee",
  "contact_id": "kn4d7b2x9q1m6v3r8c0w5h2t",
  "workflows_started": 1
}
```

`workflows_started` compte les workflows où le contact vient d’entrer. Un contact n’entre qu’une fois par workflow : envoyer deux fois le même événement ne le fait pas repartir.

## Ce qui se passe ensuite

- Un contact désabonné n’entre dans aucun workflow.
- Si aucun workflow actif n’attend ce nom, `workflows_started` vaut `0`. Ce n’est pas une erreur.
- Les champs `first_name` et `last_name` complètent le contact s’il existe déjà.

Le détail de chaque champ est dans [Introduction à l’API](/docs/reference/api/#evenements).

## Si ça ne marche pas

| Réponse                   | Cause                                                                 | Quoi faire                                                                 |
| ------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `401 missing_api_key`     | Pas d’en-tête `Authorization`.                                        | Ajoute `Authorization: Bearer …`.                                          |
| `403 invalid_api_key`     | Clé inconnue ou révoquée.                                             | Vérifie la variable d’environnement, ou crée une nouvelle clé.             |
| `422`                     | Nom d’événement invalide.                                             | Le nom ne garde que les lettres minuscules, les chiffres, `.`, `_` et `-`. |
| `429 rate_limit_exceeded` | Trop d’écritures en peu de temps.                                     | Attends un peu, puis réessaie.                                             |
| `workflows_started: 0`    | Aucun workflow actif n’attend ce nom, ou le contact y est déjà passé. | Vérifie le nom exact dans le déclencheur, et que le workflow est actif.    |