Événements d’espace de travail

Définissez des événements d’espace de travail et les types de leurs propriétés, pour que les événements w: que vous envoyez soient vérifiés.

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

POST/workspace/events
GET/workspace/events/{id}
POST/workspace/events/{id}
GET/workspace/events
DEL/workspace/events/{id}

Créer un événement d’espace de travail

Définit un événement d’espace de travail : un nom et les propriétés que porte chaque événement de ce type, chacune avec un type. Vous l’envoyez ensuite sous la forme w:<name>, et Emailit rejette les événements qui ne correspondent pas. Nécessite une clé API avec la portée full.

Les événements d’espace de travail sont inclus dans les forfaits Pro, Business et Custom. Un espace de travail peut en définir autant que son forfait compte de types d’événements : 100 sur Pro et 1 000 sur Business, sans limite sur Custom. Les événements personnalisés (c:<name>) ne nécessitent aucune définition. Consultez Événements d’espace de travail.

POST/workspace/events

Paramètres du corps

namestringobligatoire

Le nom de l’événement, par exemple customer.type : de 1 à 100 lettres, chiffres, ., - ou _, en commençant par une lettre ou un chiffre. Vous pouvez aussi l’envoyer avec le préfixe (w:customer.type) ; le préfixe est retiré. Doit être unique dans l’espace de travail.

titlestring | null

Un nom lisible affiché dans le tableau de bord, 120 caractères au maximum.

descriptionstring | null

Note pour votre équipe, 1 000 caractères au maximum.

propertiesobject[]

Jusqu’à 50 définitions de propriétés. Par défaut : [], ce qui signifie que les événements de ce type ne portent aucune propriété. Chacune comporte :

name (obligatoire) : de 1 à 64 lettres, chiffres, - ou _, en commençant par une lettre ou un chiffre. Les points ne sont pas autorisés, car les filtres de webhook et les modèles utilisent les points pour accéder aux valeurs imbriquées. Les noms doivent être uniques dans la définition.
type (obligatoire) : string, number, date ou boolean, quelle que soit la casse.
title : un libellé, 120 caractères au maximum.
description : 1 000 caractères au maximum.
required : true si chaque événement doit inclure la propriété. Par défaut : false.

Réponse

Renvoie 201 Created avec l’objet événement d’espace de travail.

Statut	Cas
`403`	La clé API n’a pas la portée `full`, ou l’espace de travail est sur Pay as you go : `error` vaut `plan_required` et `required_plan` vaut `pro`.
`409`	Un événement d’espace de travail portant ce nom existe déjà. `errors.name` l’indique.
`422`	Un champ est invalide : `errors` est indexé par son chemin, comme `name` ou `properties.1.type`, et `message` reprend le premier problème. Renvoyé aussi avec `code: "workspace_events_limit"` lorsque l’espace de travail compte déjà autant d’événements d’espace de travail que son forfait le permet, et pour un nom qui commence par `c:`.

POST/workspace/events

Terminal

curl -X POST https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer.type",
    "title": "Customer type",
    "description": "Set when a customer'\''s account type changes in the shop.",
    "properties": [
      { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
      { "name": "since", "type": "date" }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'customer.type',
    title: 'Customer type',
    description: "Set when a customer's account type changes in the shop.",
    properties: [
      { name: 'segment', type: 'string', title: 'Segment', description: 'b2b or b2c', required: true },
      { name: 'since', type: 'date' },
    ],
  }),
});
const definition = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/workspace/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "customer.type",
        "title": "Customer type",
        "description": "Set when a customer's account type changes in the shop.",
        "properties": [
            {"name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": True},
            {"name": "since", "type": "date"},
        ],
    },
)
definition = r.json()

PHP

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

$response = $client->post('workspace/events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'customer.type',
        'title' => 'Customer type',
        'description' => "Set when a customer's account type changes in the shop.",
        'properties' => [
            ['name' => 'segment', 'type' => 'string', 'title' => 'Segment', 'description' => 'b2b or b2c', 'required' => true],
            ['name' => 'since', 'type' => 'date'],
        ],
    ],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T08:00:00.000000+00:00"
}

JSON

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

JSON

{
  "error": "w:customer.type is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}

JSON

{
  "error": "properties.1.type must be one of string, number, date, boolean",
  "message": "properties.1.type must be one of string, number, date, boolean",
  "errors": {
    "properties.1.type": ["must be one of string, number, date, boolean"]
  }
}

Récupérer un événement d’espace de travail

Récupère la définition d’un événement d’espace de travail : son nom, son titre et les propriétés que doivent respecter les événements envoyés. Nécessite une clé API avec la portée full.

GET/workspace/events/{id}

Paramètres de chemin

idstringobligatoire

L’ID de la définition (etp_…), son nom (customer.type) ou son type d’événement (w:customer.type). Encodez le : pour l’URL si votre client ne le fait pas.

Réponse

Renvoie l’objet événement d’espace de travail.

objectstring

Toujours workspace_event.

idstring

ID de la définition, préfixé par etp_.

namestring

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

typestring

Le type à envoyer et sur lequel filtrer : w: suivi du nom.

titlestring | null

Un nom lisible, affiché dans le tableau de bord à la place du type, par exemple dans l’activité d’un contact.

descriptionstring | null

Note pour votre équipe.

propertiesobject[]

Les propriétés que peut porter un événement de ce type, chacune avec :

name : la clé dans les properties de l’événement.
type : string, number, date ou boolean. Consultez Types de propriétés.
title, description : des libellés facultatifs, ou null.
required : indique si chaque événement doit l’inclure.

created_at, updated_atstring

Horodatages en UTC.

Renvoie 404 avec error: "Workspace event not found" si aucune définition ne correspond.

GET/workspace/events/{id}

Terminal

curl https://api.emailit.com/v2/workspace/events/w%3Acustomer.type \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/customer.type', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const definition = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/workspace/events/customer.type",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
definition = r.json()

PHP

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

$response = $client->get('workspace/events/customer.type', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T08:00:00.000000+00:00"
}

JSON

{
  "error": "Workspace event not found"
}

Mettre à jour un événement d’espace de travail

Met à jour les champs transmis et laisse les autres inchangés. Nécessite une clé API avec la portée full.

La définition ne vérifie que les nouveaux événements. Les événements déjà enregistrés conservent leur type et leurs propriétés : après une modification, des événements plus anciens peuvent donc avoir des propriétés que la définition ne liste plus.

properties remplace toute la liste. Pour ajouter une propriété, envoyez la liste actuelle avec la nouvelle.
Renommer change le type à envoyer. Les événements enregistrés sous l’ancien nom le conservent, et les nouveaux événements portant l’ancien nom sont rejetés, sauf si vous le définissez à nouveau.

POST/workspace/events/{id}

Paramètres de chemin

idstringobligatoire

L’ID de la définition (etp_…), son nom ou son type d’événement (w:…).

Paramètres du corps

namestring

Un nouveau nom, avec les mêmes règles qu’à la création.

titlestring | null

120 caractères au maximum. null ou une chaîne vide l’efface.

descriptionstring | null

1 000 caractères au maximum. null ou une chaîne vide l’efface.

propertiesobject[]

La nouvelle liste de propriétés, 50 au maximum, comme à la création. [] retire toutes les propriétés.

Réponse

Renvoie l’objet événement d’espace de travail mis à jour.

Statut	Cas
`404`	Aucune définition ne correspond à `id`.
`409`	Un autre événement d’espace de travail porte déjà le nouveau nom.
`422`	Un champ est invalide : `errors` est indexé par son chemin, et `message` reprend le premier problème.

POST/workspace/events/{id}

Terminal

curl -X POST https://api.emailit.com/v2/workspace/events/customer.type \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      { "name": "segment", "type": "string", "title": "Segment", "required": true },
      { "name": "since", "type": "date" },
      { "name": "vat_exempt", "type": "boolean" }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/customer.type', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    properties: [
      { name: 'segment', type: 'string', title: 'Segment', required: true },
      { name: 'since', type: 'date' },
      { name: 'vat_exempt', type: 'boolean' },
    ],
  }),
});
const definition = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/workspace/events/customer.type",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "properties": [
            {"name": "segment", "type": "string", "title": "Segment", "required": True},
            {"name": "since", "type": "date"},
            {"name": "vat_exempt", "type": "boolean"},
        ]
    },
)
definition = r.json()

PHP

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

$response = $client->post('workspace/events/customer.type', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'properties' => [
            ['name' => 'segment', 'type' => 'string', 'title' => 'Segment', 'required' => true],
            ['name' => 'since', 'type' => 'date'],
            ['name' => 'vat_exempt', 'type' => 'boolean'],
        ],
    ],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": null, "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false },
    { "name": "vat_exempt", "type": "boolean", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T10:12:45.000000+00:00"
}

JSON

{
  "error": "w:customer.segment is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}

Lister les événements d’espace de travail

Renvoie les définitions d’événements de l’espace de travail, triées par nom. Nécessite une clé API avec la portée full.

GET/workspace/events

Paramètres de requête

pageintegerpar défaut : 1

Numéro de page, à partir de 1.

limitintegerpar défaut : 100

Définitions par page, de 1 à 250.

searchstring

Correspondance insensible à la casse sur une partie du nom ou du titre.

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.

Clés de filtre

Les filtres utilisent des paramètres de requête key.condition=value, par exemple name.starts_with=order. ou created_at.after=2026-10-01. Pour les conditions disponibles selon le type, consultez Filtrage et tri.

Clé	Type	Remarques
`name`	chaîne	Le nom sans le préfixe `w:`.
`title`	chaîne
`created_at`	date
`updated_at`	date

Clés de tri pour order : name, title, created_at, updated_at. Par défaut : name, par ordre croissant.

Réponse

dataobject[]

Objets événement d’espace de travail de cette page.

total_recordsinteger

Nombre de définitions qui correspondent à la requête.

next_page_urlstring | null

Chemin de la page suivante, ou null sur la dernière page. Il ne contient que page et limit ; ajoutez de nouveau votre recherche et vos filtres lorsque vous le suivez.

previous_page_urlstring | null

Chemin de la page précédente, ou null sur la première page.

GET/workspace/events

Terminal

curl -G https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "search=customer"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events?search=customer', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data, total_records } = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/workspace/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"search": "customer"},
)
definitions = r.json()["data"]

PHP

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

$response = $client->get('workspace/events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['search' => 'customer'],
]);
$definitions = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    {
      "object": "workspace_event",
      "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
      "name": "customer.type",
      "type": "w:customer.type",
      "title": "Customer type",
      "description": "Set when a customer's account type changes in the shop.",
      "properties": [
        { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
        { "name": "since", "type": "date", "title": null, "description": null, "required": false }
      ],
      "created_at": "2026-10-19T08:00:00.000000+00:00",
      "updated_at": "2026-10-19T08:00:00.000000+00:00"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Supprimer un événement d’espace de travail

Supprime la définition d’un événement d’espace de travail. Nécessite une clé API avec la portée full.

Les événements déjà enregistrés avec ce type sont conservés, dans le journal des événements et sur les contacts. Les nouveaux événements de ce type sont rejetés avec 422 jusqu’à ce que vous le définissiez à nouveau. Les webhooks abonnés à ce type conservent leur abonnement.

DELETE/workspace/events/{id}

Paramètres de chemin

idstringobligatoire

L’ID de la définition (etp_…), son nom ou son type d’événement (w:…).

Réponse

objectstring

Toujours workspace_event.

idstring

ID de la définition supprimée.

namestring

Son nom.

typestring

Son type d’événement, w: suivi du nom.

deletedboolean

Toujours true.

Renvoie 404 si aucune définition ne correspond.

DELETE/workspace/events/{id}

Terminal

curl -X DELETE https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();

Python

import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

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

$response = $client->delete('workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "deleted": true
}