# Événements d’espace de travail API

> 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 base : `https://api.emailit.com/v2`. Authentifiez-vous avec `Authorization: Bearer <API key>`.

## Créer un événement d’espace de travail — POST /workspace/events

> Définissez un événement d’espace de travail et ses propriétés typées. Les événements de ce type s’envoient ensuite avec le préfixe w: et sont vérifiés par rapport à la définition.

# 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](/fr/docs/events/workspace-events/).

`POST /workspace/events`

## Paramètres du corps

- `name` (string, obligatoire): 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.

- `title` (string | null): Un nom lisible affiché dans le tableau de bord, 120 caractères au maximum.

- `description` (string | null): Note pour votre équipe, 1 000 caractères au maximum.

- `properties` (object[]): 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](/fr/docs/api-reference/workspace-events/get/).

| 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:`. |

**Requête** `POST /workspace/events`

**cURL**

```bash
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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**201**

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

**403**

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

**409**

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

**422**

```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"]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/workspace-events/create/

## Récupérer un événement d’espace de travail — GET /workspace/events/{id}

> Récupérez la définition d’un événement d’espace de travail par son ID ou son nom, avec ses propriétés typées.

# 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

- `id` (string, obligatoire): 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.

- `object` (string): Toujours `workspace_event`.

- `id` (string): ID de la définition, préfixé par `etp_`.

- `name` (string): Le nom de l’événement, sans le préfixe.

- `type` (string): Le type à envoyer et sur lequel filtrer : `w:` suivi du nom.

- `title` (string | null): Un nom lisible, affiché dans le tableau de bord à la place du type, par exemple dans l’activité d’un contact.

- `description` (string | null): Note pour votre équipe.

- `properties` (object[]): 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](/fr/docs/events/workspace-events/#property-types). - `title`, `description` : des libellés facultatifs, ou `null`. - `required` : indique si chaque événement doit l’inclure.

- `created_at, updated_at` (string): Horodatages en UTC.

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

**Requête** `GET /workspace/events/{id}`

**cURL**

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

**Node.js**

```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**

```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**

```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);
```

**200**

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

**404**

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

---
Source: https://emailit.com/fr/docs/api-reference/workspace-events/get/

## Mettre à jour un événement d’espace de travail — POST /workspace/events/{id}

> Renommez un événement d’espace de travail ou modifiez son titre, sa description ou ses propriétés. Les événements déjà enregistrés ne changent pas.

# 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

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

## Paramètres du corps

- `name` (string): Un nouveau nom, avec les mêmes règles qu’à la [création](/fr/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): 120 caractères au maximum. `null` ou une chaîne vide l’efface.

- `description` (string | null): 1 000 caractères au maximum. `null` ou une chaîne vide l’efface.

- `properties` (object[]): La nouvelle liste de propriétés, 50 au maximum, comme à la [création](/fr/docs/api-reference/workspace-events/create/#body-parameters). `[]` retire toutes les propriétés.

## Réponse

Renvoie l’[objet événement d’espace de travail](/fr/docs/api-reference/workspace-events/get/) 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. |

**Requête** `POST /workspace/events/{id}`

**cURL**

```bash
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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**200**

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

**409**

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

---
Source: https://emailit.com/fr/docs/api-reference/workspace-events/update/

## Lister les événements d’espace de travail — GET /workspace/events

> Listez les définitions d’événements de l’espace de travail, triées par nom, avec leurs propriétés typées, une recherche et des filtres.

# 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

- `page` (integer): Numéro de page, à partir de 1.

- `limit` (integer): Définitions par page, de 1 à 250.

- `search` (string): Correspondance insensible à la casse sur une partie du nom ou du titre.

- `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

### 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](/fr/docs/api-reference/filtering/).

| 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

- `data` (object[]): [Objets événement d’espace de travail](/fr/docs/api-reference/workspace-events/get/) de cette page.

- `total_records` (integer): Nombre de définitions qui correspondent à la requête.

- `next_page_url` (string | 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_url` (string | null): Chemin de la page précédente, ou `null` sur la première page.

**Requête** `GET /workspace/events`

**cURL**

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

**Node.js**

```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**

```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**

```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'];
```

**200**

```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
}
```

---
Source: https://emailit.com/fr/docs/api-reference/workspace-events/list/

## Supprimer un événement d’espace de travail — DELETE /workspace/events/{id}

> Supprimez la définition d’un événement d’espace de travail. Les événements enregistrés sont conservés, et les nouveaux événements de ce type sont rejetés.

# 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

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

## Réponse

- `object` (string): Toujours `workspace_event`.

- `id` (string): ID de la définition supprimée.

- `name` (string): Son nom.

- `type` (string): Son type d’événement, `w:` suivi du nom.

- `deleted` (boolean): Toujours `true`.

Renvoie `404` si aucune définition ne correspond.

**Requête** `DELETE /workspace/events/{id}`

**cURL**

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

**Node.js**

```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**

```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**

```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);
```

**200**

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

---
Source: https://emailit.com/fr/docs/api-reference/workspace-events/delete/