# Envoyer des événements depuis votre backend

> Enregistrez des événements d’espace de travail et des événements personnalisés depuis vos serveurs avec l’API des événements, un par un ou par lots, avec une clé API Events Only.

Envoyez les événements depuis vos serveurs pour tout ce qui ne doit pas dépendre du navigateur du visiteur, comme les commandes, les paiements, les changements d’abonnement ou les événements d’un back-office. Cette page montre comment envoyer un événement, comment en envoyer plusieurs et comment gérer les erreurs.

## Avant de commencer

- L’envoi d’événements est inclus dans les forfaits Pro, Business et Custom. Un espace de travail Pro peut utiliser 100 types d’événements et un espace de travail Business 1 000. Consultez [Limites](/fr/docs/events/#limits).
- Créez une clé API avec la portée **Events Only** dans **Email API → API Keys**. Elle peut envoyer des événements et rien d’autre : elle ne peut ni lire vos données, ni gérer les définitions d’événements, ni envoyer d’e-mails. Une clé **Full Access** fonctionne aussi. Consultez [Clés API](/fr/docs/developers/api-keys/#scopes).
- Pour envoyer des événements d’espace de travail, [définissez-les](/fr/docs/events/workspace-events/) d’abord. Les événements personnalisés ne demandent aucune configuration.

## Envoyer un événement

Appelez [Envoyer un événement](/fr/docs/api-reference/events/send/) avec le `type` de l’événement, ses `properties` et la personne qu’il concerne :

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'
```

- `email` rattache l’événement au contact qui a cette adresse. Si vous connaissez déjà l’ID du contact, envoyez plutôt `contact_id`.
- `occurred_at` indique quand l’événement s’est produit, par exemple lorsque vous envoyez des événements depuis une file d’attente. Omettez-le pour utiliser l’heure actuelle.
- La réponse est `201`, avec l’événement enregistré et son ID `evt_`. Une clé Events Only reçoit l’événement sans `data`.

## Envoyer plusieurs événements à la fois

[Envoyer des événements par lot](/fr/docs/api-reference/events/batch/) accepte jusqu’à 100 événements en une seule requête, ce qui convient aux imports et aux synchronisations planifiées :

```bash
curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } }
    ]
  }'
```

Un lot est traité en tout ou rien : si un événement est invalide, aucun n’est enregistré. La réponse `422` liste chaque problème sous `events.<index>` : vous pouvez ainsi corriger ou retirer ces événements, puis renvoyer le lot.

## Gérer les erreurs

| Statut | Signification | Que faire |
| --- | --- | --- |
| `201` | Enregistré. | Rien. |
| `400` | Le corps n’est pas un objet JSON, ou le lot est vide ou contient plus de 100 événements. | Corrigez la requête. |
| `401` | La clé API est absente ou incorrecte. | Vérifiez la clé. |
| `403` | La portée de la clé ne permet pas d’envoyer des événements, ou l’espace de travail est sur Pay as you go (`"error": "plan_required"`). | Utilisez une clé Events Only ou Full Access, ou passez au forfait Pro ou Business. |
| `422` | Un événement est invalide : un événement `w:` non défini, une propriété du mauvais type, un `contact_id` inconnu, une date située plus de 24 heures dans le futur, ou un nouveau type d’événement alors que l’espace de travail utilise déjà le nombre de types de son forfait. `errors` nomme chaque champ. | Corrigez l’événement, ou passez à un forfait supérieur pour avoir plus de types d’événements. Le relancer sans modification échoue de nouveau. |
| `5xx` | Un problème temporaire du côté d’Emailit. | Relancez avec un intervalle exponentiel. |

Les événements n’ont pas de clé d’idempotence : relancer une requête qui a abouti enregistre donc l’événement deux fois. Placez votre propre ID dans les propriétés, comme `order_id`, pour que quiconque lit les événements puisse reconnaître les doublons.

## Vérifier que les événements arrivent

Ouvrez **Email API → Events**. L’onglet **Log** liste les nouveaux événements en haut ; réglez **Scope** sur **Custom** ou **Workspace** pour masquer les événements système. Sélectionnez un événement pour voir ses propriétés, le contact auquel il appartient et sa provenance. Les événements rattachés à un contact apparaissent aussi dans l’**Activity log** du contact.

## Voir aussi

  - [Suivi des événements](/fr/docs/events/): Portées, noms et destination des événements.
  - [Script de suivi](/fr/docs/events/tracking-script/): Envoyez des événements depuis votre site web.
  - [Envoyer un événement](/fr/docs/api-reference/events/send/): Chaque paramètre et chaque réponse.
  - [Clés API](/fr/docs/developers/api-keys/): Créez une clé Events Only.

---
Source: https://emailit.com/fr/docs/events/send-events/