Événements

Envoyez des événements d’espace de travail et des événements personnalisés, et consultez le flux d’événements derrière les webhooks : livraisons, rebonds, ouvertures et plus encore.

URL de basehttps://api.emailit.com/v2Authentification Erreurs Limites de débit

POST/events
POST/events/batch
GET/events
GET/events/{id}

Envoyer un événement

Enregistre un événement d’espace de travail (w:<name>) ou un événement personnalisé (c:<name>). Fonctionne avec les clés API de portée full ou events. Pour savoir lequel utiliser, consultez Suivi des événements. Les événements sont inclus dans les forfaits Pro, Business et Custom, avec 100 types d’événements au maximum sur Pro et 1 000 sur Business.

Un événement d’espace de travail doit d’abord être défini. Ses properties sont vérifiées par rapport à la définition.
Un événement personnalisé ne nécessite aucune définition. Ses properties peuvent être n’importe quel objet JSON.

Les événements système comme email.delivered sont enregistrés par Emailit et ne peuvent pas être envoyés. Pour enregistrer de nombreux événements en un seul appel, utilisez Envoyer des événements par lot.

POST/events

Paramètres du corps

typestringobligatoire

w:<name> pour un événement d’espace de travail ou c:<name> pour un événement personnalisé, par exemple c:order.completed. Le nom compte de 1 à 100 lettres, chiffres, ., - ou _, et commence par une lettre ou un chiffre.

propertiesobject

Les données de l’événement. Par défaut : {}.

Événements d’espace de travail : uniquement les propriétés de la définition, chacune avec son type. Les propriétés obligatoires doivent être présentes, null laisse vide une propriété facultative, et les dates sont enregistrées au format ISO 8601 en UTC. Consultez Types de propriétés.
Événements personnalisés : n’importe quel objet JSON, jusqu’à 32 Ko et 8 niveaux d’imbrication.

emailstring

L’adresse e-mail de la personne concernée par l’événement. Si un contact possède cette adresse, l’événement est attribué à ce contact. Sinon, l’adresse est tout de même enregistrée, et l’événement apparaît dans l’activité du contact dès que vous le créez.

contact_idstring

L’ID d’un contact existant (con_…). Prioritaire sur email. Un ID qui ne correspond à aucun contact de l’espace de travail renvoie 422.

anonymous_idstring

Votre propre identifiant d’un visiteur ou d’un appareil, 128 caractères au maximum, pour les événements que vous ne pouvez pas encore rattacher à une personne.

occurred_atstring | integer

Le moment où l’événement s’est produit : une date-heure ISO 8601 ou un horodatage en millisecondes. Par défaut : maintenant. Peut se situer dans le passé, mais pas plus de 24 heures dans le futur.

contextobject

L’endroit où l’événement s’est produit : page (url, path, title, referrer, search), campaign (source, medium, name, term, content), locale et timezone. Les clés inconnues sont supprimées et les valeurs trop longues sont raccourcies.

Les contacts sont seulement recherchés, jamais créés. Emailit n’enregistre pas d’adresses IP avec les événements.

Réponse

Renvoie 201 Created avec l’événement : object, id, type, created_at et data. data.object contient ce qui a été enregistré :

objectstring

workspace_event ou custom_event.

namestring

Le nom de l’événement, sans son préfixe.

propertiesobject

Les propriétés validées.

contactobject | null

id et email du contact auquel appartient l’événement. id vaut null lorsque seule l’adresse e-mail est connue. null si vous n’avez envoyé ni l’un ni l’autre.

anonymous_idstring | null

L’anonymous_id que vous avez envoyé.

occurred_atstring

Le moment où l’événement s’est produit, en UTC.

sourcestring

api pour cet endpoint. Les événements du script de suivi ont js, et les événements de test envoyés depuis le tableau de bord ont dashboard.

contextobject

Le contexte enregistré. Absent s’il n’y en a pas.

Une clé API de portée events ne peut pas lire de données : elle reçoit donc l’événement sans data, qui contient le contact retrouvé par son adresse e-mail.

Statut	Cas
`400`	Le corps n’est pas un objet JSON.
`403`	La portée de la clé API n’est ni `full` ni `events`, ou le forfait n’inclut pas les événements d’espace de travail et personnalisés : sur Pay as you go, `error` vaut `plan_required` et `required_plan` vaut `pro`. Rien n’est enregistré.
`422`	L’événement est invalide. `errors` est indexé par champ, comme `type` ou `properties.total`, et `message` reprend le premier problème. Renvoyé aussi pour un événement `w:` qui n’est pas défini, pour un `contact_id` qui ne correspond à aucun contact, et pour un type que l’espace de travail n’a jamais envoyé une fois qu’il utilise le nombre de types d’événements de son forfait (100 sur Pro, 1 000 sur Business).
`429`	Trop de requêtes en une minute, ou l’espace de travail a atteint sa limite quotidienne d’usage raisonnable pour les événements d’espace de travail et personnalisés (`code` : `events_daily_limit`). Rien n’est enregistré. Réessayez après le nombre de secondes indiqué dans l’en-tête `retry-after`.

POST/events

Terminal

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"
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'c:order.completed',
    email: 'jane@example.com',
    properties: { order_id: '1001', total: 59.9, currency: 'EUR' },
    occurred_at: '2026-10-19T09:30:00Z',
  }),
});
const event = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "type": "c:order.completed",
        "email": "jane@example.com",
        "properties": {"order_id": "1001", "total": 59.9, "currency": "EUR"},
        "occurred_at": "2026-10-19T09:30:00Z",
    },
)
event = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'type' => 'c:order.completed',
        'email' => 'jane@example.com',
        'properties' => ['order_id' => '1001', 'total' => 59.9, 'currency' => 'EUR'],
        'occurred_at' => '2026-10-19T09:30:00Z',
    ],
]);
$event = json_decode($response->getBody(), true);

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00",
  "data": {
    "object": {
      "object": "custom_event",
      "name": "order.completed",
      "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
      "contact": { "id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "email": "jane@example.com" },
      "anonymous_id": null,
      "occurred_at": "2026-10-19T09:30:00.000Z",
      "source": "api"
    }
  }
}

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00"
}

JSON

{
  "error": "plan_required",
  "required_plan": "pro",
  "message": "Workspace and custom events are included with Pro and Business."
}

JSON

{
  "error": "properties.segment must be a string",
  "message": "properties.segment must be a string",
  "errors": {
    "properties.segment": ["must be a string"]
  }
}

JSON

{
  "error": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "message": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "errors": {
    "type": ["w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier)."]
  }
}

Envoyer des événements par lot

Enregistre jusqu’à 100 événements d’espace de travail et événements personnalisés en une seule requête, par exemple lorsque votre backend synchronise des commandes à intervalles réguliers. Fonctionne avec les clés API de portée full ou events, sur les forfaits Pro, Business et Custom.

Le lot est traité en tout ou rien. Si un événement est invalide, aucun n’est enregistré, et la réponse liste chaque problème selon la position de l’événement dans la liste.

POST/events/batch

Paramètres du corps

eventsobject[]obligatoire

De 1 à 100 événements. Chacun accepte les mêmes champs que Envoyer un événement : type, properties, email, contact_id, anonymous_id, occurred_at et context.

Réponse

Renvoie 201 Created avec les événements enregistrés dans data, dans l’ordre où vous les avez envoyés. Chaque élément contient object (event), id, type et created_at. Utilisez Récupérer un événement pour en lire un avec son data.

Statut	Cas
`400`	`events` est absent, vide ou contient plus de 100 éléments.
`403`	La portée de la clé API n’est ni `full` ni `events`, ou le forfait n’inclut pas les événements d’espace de travail et personnalisés : sur Pay as you go, `error` vaut `plan_required` et `required_plan` vaut `pro`. Rien n’est enregistré.
`422`	Au moins un événement est invalide. Rien n’est enregistré. `errors` est indexé par `events.<index>.<field>`, par exemple `events.3.properties.total`, en comptant à partir de 0, et `message` reprend le premier problème. Un événement d’un type que l’espace de travail n’a jamais envoyé est invalide une fois que l’espace de travail utilise le nombre de types d’événements de son forfait (100 sur Pro, 1 000 sur Business).
`429`	Trop de requêtes en une minute, ou le lot ferait dépasser à l’espace de travail sa limite quotidienne d’usage raisonnable pour les événements d’espace de travail et personnalisés (`code` : `events_daily_limit`). Rien n’est enregistré. Réessayez après le nombre de secondes indiqué dans l’en-tête `retry-after`.

POST/events/batch

Terminal

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 } },
      { "type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": { "segment": "b2b" } }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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 } },
      { type: 'w:customer.type', contact_id: 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', properties: { segment: 'b2b' } },
    ],
  }),
});
const { data } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events/batch",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "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}},
            {"type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": {"segment": "b2b"}},
        ]
    },
)
stored = r.json()["data"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('events/batch', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        '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]],
            ['type' => 'w:customer.type', 'contact_id' => 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', 'properties' => ['segment' => 'b2b']],
        ],
    ],
]);
$stored = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    { "object": "event", "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Sa1XcP4uW8rMyB6fGjK0nT", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Td5ZeQ7vX2sNzC9hHkL3pU", "type": "w:customer.type", "created_at": "2026-10-19T09:30:02.114000+00:00" }
  ]
}

JSON

{
  "error": "events.1.email must be a valid email address",
  "message": "events.1.email must be a valid email address",
  "errors": {
    "events.1.email": ["must be a valid email address"],
    "events.2.properties.segment": ["must be a string"]
  }
}

Lister les événements

Renvoie les événements de votre espace de travail, du plus récent au plus ancien. Chaque livraison de webhook est construite à partir de l’un de ces événements : vous pouvez donc utiliser cet endpoint pour récupérer après coup les événements que votre endpoint a manqués. Nécessite une clé API de portée full.

GET/events

Paramètres de requête

pageinteger

Numéro de page, à partir de 1. Par défaut : 1. Les pages situées au-delà de 2 500 événements ((page - 1) × limit > 2500) renvoient 422.

limitinteger

Nombre d’événements par page, de 1 à 100. Par défaut : 100.

typestring

Type d’événement, ou liste de types séparés par des virgules, par exemple email.delivered,email.bounced. Les événements d’espace de travail et les événements personnalisés conservent leur préfixe, par exemple c:order.completed. Consultez Types d’événements.

scopestring

Uniquement les événements de ces portées, séparées par des virgules : system (les événements qu’enregistre Emailit, comme email.delivered), workspace (les événements définis par l’espace de travail, w:<name>) et custom (les événements personnalisés, c:<name>). Par exemple, scope=workspace,custom. Par défaut : toutes les portées. Une portée inconnue renvoie 400.

include_databoolean

Définissez true pour inclure le payload data de chaque événement. Par défaut : false, qui ne renvoie que object, id, type et created_at.

matchstring

all (par défaut) exige que tous les filtres correspondent. Avec or, il suffit qu’un filtre corresponde. Consultez Filtrage et tri.

orderstring

Clé de tri de cette liste. Consultez les clés de tri ci-dessous.

directionstring

asc ou desc.

Filtres et tri

Les filtres de liste sont des paramètres de requête key.condition=value sur un seul niveau. Consultez Filtrage et tri pour match, order, direction et la liste des conditions par type.

Clés de filtre

Clé	Type	Conditions	Remarques
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Clés de tri

Passez dans order l’une de ces clés et dans direction la valeur asc ou desc : type, created_at

Sans filtre created_at, la liste ne couvre que les 2 derniers jours. Pour remonter plus loin, ajoutez-en un, par exemple created_at.after=2026-09-01T00:00:00Z. Les événements plus anciens restent disponibles tant que la conservation des données de votre forfait les garde.

Réponse

Renvoie 200 OK avec les événements dans data, ainsi que next_page_url et previous_page_url (null aux deux extrémités). Les URL de page conservent type, scope, limit et include_data.

Renvoie 422 avec code: "events_offset_too_large" lorsque la page est trop profonde. Réduisez la plage de dates ou les types plutôt que de paginer plus loin.

GET/events

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const events = await emailit.events.list({ type: 'email.delivered' });

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

events = client.events.list({"type": "email.delivered"})

PHP

$emailit = Emailit::client('your_api_key');

$events = $emailit->events()->list(['type' => 'email.delivered']);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

events = client.events.list(type: "email.delivered")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

events, err := client.Events.List(&emailit.ListEventsRequest{Type: "email.delivered"})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let events = emailit.events.list(Some(emailit::types::ListEventsParams { r#type: Some("email.delivered".into()), ..Default::default() })).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject events = emailit.events().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var events = emailit.Events.List(new EventListOptions { Type = "email.delivered" });

PHP

use Emailit\Laravel\Facades\Emailit;

$events = Emailit::events()->list(['type' => 'email.delivered']);

Terminal

curl -X GET "https://api.emailit.com/v2/events?type=email.delivered" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered",
  "previous_page_url": null
}

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "data": {
        "object": {
          "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
          "object": "email",
          "from": "hello@acme.com",
          "to": "ada@example.com",
          "subject": "Your order has shipped",
          "status": "delivered",
          "meta": { "order_id": "1042" },
          "updated_at": "2026-10-01T10:02:14.307000+00:00",
          "created_at": "2026-10-01T10:02:11.583000+00:00"
        }
      },
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered&include_data=true",
  "previous_page_url": null
}

JSON

{
  "error": "Page is too deep. Narrow the type or date filter, or open an earlier page.",
  "code": "events_offset_too_large"
}

Récupérer un événement

Renvoie un événement avec son payload data complet. L’id est la même valeur que celle que les webhooks envoient dans event_id : vous pouvez donc retrouver n’importe quel événement reçu. Nécessite une clé API de portée full.

GET/events/:id

Paramètres de chemin

idstringObligatoire

ID de l’événement, par exemple evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a.

Réponse

Renvoie 200 OK avec l’événement : object (event), id, type, data et created_at. data.object a la même forme que dans le payload de webhook de ce type ; consultez la référence des événements webhook.

Pour les événements d’espace de travail (w:) et les événements personnalisés (c:), data.object contient object (workspace_event ou custom_event), name, properties, contact, anonymous_id, occurred_at, source, identity_verified pour les événements du script de suivi qui nomment un contact et, s’il y en a un, context. Consultez Envoyer un événement.

Renvoie 404 avec error: "Event not found" si l’ID n’existe pas dans votre espace de travail.

GET/events/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const event = await emailit.events.get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

PHP

$emailit = Emailit::client('your_api_key');

$event = $emailit->events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

event, err := client.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let event = emailit.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a").await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject event = emailit.events().get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var ev = emailit.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

PHP

use Emailit\Laravel\Facades\Emailit;

$event = Emailit::events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Terminal

curl https://api.emailit.com/v2/events/evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "event",
  "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
      "object": "email",
      "from": "hello@acme.com",
      "to": "ada@example.com",
      "subject": "Your order has shipped",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T10:02:14.307000+00:00",
      "created_at": "2026-10-01T10:02:11.583000+00:00"
    }
  },
  "created_at": "2026-10-01T10:02:15.912000+00:00"
}

JSON

{
  "error": "Event not found"
}