# Eventi di workspace API

> Definisci gli eventi di workspace e i tipi delle loro proprietà, così gli eventi w: che invii vengono controllati.

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea un evento di workspace — POST /workspace/events

> Definisci un evento di workspace e le sue proprietà tipizzate. Gli eventi di questo tipo vengono poi inviati con il prefisso w: e controllati rispetto alla definizione.

# Crea un evento di workspace

Definisce un evento di workspace: un nome e le proprietà che ogni evento di quel tipo contiene, ciascuna con un tipo. Poi lo invii come `w:<name>`, ed Emailit rifiuta gli eventi che non corrispondono. Richiede una chiave API con il permesso `full`.

Gli eventi di workspace sono inclusi nei piani Pro, Business e Custom. Un workspace può definirne tanti quanti sono i tipi di evento del suo piano: 100 con Pro e 1000 con Business, senza limiti con Custom. Gli eventi personalizzati (`c:<name>`) non richiedono una definizione. Vedi [Eventi di workspace](/it/docs/events/workspace-events/).

`POST /workspace/events`

## Parametri del corpo

- `name` (string, obbligatorio): Il nome dell’evento, ad esempio `customer.type`: da 1 a 100 caratteri tra lettere, cifre, `.`, `-` o `_`, che inizia con una lettera o una cifra. Puoi inviarlo anche con il prefisso (`w:customer.type`); il prefisso viene rimosso. Deve essere univoco nel workspace.

- `title` (string | null): Un nome leggibile mostrato nel pannello, fino a 120 caratteri.

- `description` (string | null): Nota per il team, fino a 1000 caratteri.

- `properties` (object[]): Fino a 50 definizioni di proprietà. Predefinito `[]`, cioè gli eventi di questo tipo non contengono proprietà. Ognuna ha: - `name` (obbligatorio): da 1 a 64 caratteri tra lettere, cifre, `-` o `_`, che inizia con una lettera o una cifra. I punti non sono ammessi, perché i filtri dei webhook e i template usano i punti per raggiungere i valori annidati. I nomi devono essere univoci all’interno della definizione. - `type` (obbligatorio): `string`, `number`, `date` o `boolean`, in maiuscolo o minuscolo. - `title`: un’etichetta, fino a 120 caratteri. - `description`: fino a 1000 caratteri. - `required`: `true` se ogni evento deve includere la proprietà. Predefinito `false`.

## Restituisce

Restituisce `201 Created` con l’[oggetto evento di workspace](/it/docs/api-reference/workspace-events/get/).

| Stato | Quando |
| --- | --- |
| `403` | La chiave API non ha il permesso `full`, oppure il workspace è su Pay as you go: `error` è `plan_required` e `required_plan` è `pro`. |
| `409` | Esiste già un evento di workspace con questo nome. Lo indica `errors.name`. |
| `422` | Un campo non è valido: `errors` ha come chiave il suo percorso, ad esempio `name` o `properties.1.type`, e `message` ripete il primo problema. Viene restituito anche con `code: "workspace_events_limit"` quando il workspace ha già tanti eventi di workspace quanti ne consente il piano, e per un nome che inizia con `c:`. |

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

---
Fonte: https://emailit.com/it/docs/api-reference/workspace-events/create/

## Recupera un evento di workspace — GET /workspace/events/{id}

> Recupera la definizione di un evento di workspace per ID o per nome, con le sue proprietà tipizzate.

# Recupera un evento di workspace

Recupera la definizione di un evento di workspace: il nome, il titolo e le proprietà che chi invia l’evento deve rispettare. Richiede una chiave API con il permesso `full`.

`GET /workspace/events/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della definizione (`etp_…`), il suo nome (`customer.type`) o il suo tipo di evento (`w:customer.type`). Codifica i `:` per l’URL se il tuo client non lo fa.

## Restituisce

Restituisce l’oggetto evento di workspace.

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

- `id` (string): ID della definizione, con prefisso `etp_`.

- `name` (string): Il nome dell’evento, senza il prefisso.

- `type` (string): Il tipo da inviare e su cui filtrare: `w:` seguito dal nome.

- `title` (string | null): Un nome leggibile, mostrato nel pannello al posto del tipo, ad esempio nell’attività di un contatto.

- `description` (string | null): Nota per il team.

- `properties` (object[]): Le proprietà che un evento di questo tipo può contenere, ciascuna con: - `name`: la chiave nelle `properties` dell’evento. - `type`: `string`, `number`, `date` o `boolean`. Vedi [Tipi di proprietà](/it/docs/events/workspace-events/#property-types). - `title`, `description`: etichette facoltative, oppure `null`. - `required`: indica se ogni evento deve includerla.

- `created_at, updated_at` (string): Timestamp in UTC.

Restituisce `404` con `error: "Workspace event not found"` se nessuna definizione corrisponde.

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

---
Fonte: https://emailit.com/it/docs/api-reference/workspace-events/get/

## Aggiorna un evento di workspace — POST /workspace/events/{id}

> Rinomina un evento di workspace o modificane titolo, descrizione o proprietà. Gli eventi già memorizzati non cambiano.

# Aggiorna un evento di workspace

Aggiorna i campi che passi e lascia invariati gli altri. Richiede una chiave API con il permesso `full`.

La definizione controlla solo i nuovi eventi. Gli eventi già memorizzati mantengono il loro tipo e le loro proprietà, quindi dopo una modifica gli eventi meno recenti possono avere proprietà che la definizione non elenca più.

- `properties` sostituisce l’intero elenco. Per aggiungere una proprietà, invia l’elenco attuale più quella nuova.
- Rinominare l’evento cambia il tipo da inviare. Gli eventi memorizzati con il vecchio nome lo mantengono, e i nuovi eventi con il vecchio nome vengono rifiutati, a meno che tu non lo definisca di nuovo.

`POST /workspace/events/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della definizione (`etp_…`), il suo nome o il suo tipo di evento (`w:…`).

## Parametri del corpo

- `name` (string): Un nuovo nome, con le stesse regole valide in [creazione](/it/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): Fino a 120 caratteri. `null` o una stringa vuota lo cancellano.

- `description` (string | null): Fino a 1000 caratteri. `null` o una stringa vuota la cancellano.

- `properties` (object[]): Il nuovo elenco di proprietà, fino a 50, come in [creazione](/it/docs/api-reference/workspace-events/create/#body-parameters). `[]` rimuove tutte le proprietà.

## Restituisce

Restituisce l’[oggetto evento di workspace](/it/docs/api-reference/workspace-events/get/) aggiornato.

| Stato | Quando |
| --- | --- |
| `404` | Nessuna definizione corrisponde a `id`. |
| `409` | Un altro evento di workspace ha già il nuovo nome. |
| `422` | Un campo non è valido: `errors` ha come chiave il suo percorso, e `message` ripete il primo problema. |

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

---
Fonte: https://emailit.com/it/docs/api-reference/workspace-events/update/

## Elenca gli eventi di workspace — GET /workspace/events

> Elenca le definizioni degli eventi del workspace in ordine di nome, con le loro proprietà tipizzate, la ricerca e i filtri.

# Elenca gli eventi di workspace

Restituisce le definizioni degli eventi del workspace, ordinate per nome. Richiede una chiave API con il permesso `full`.

`GET /workspace/events`

## Parametri di query

- `page` (integer): Numero della pagina, a partire da 1.

- `limit` (integer): Definizioni per pagina, da 1 a 250.

- `search` (string): Corrispondenza su una parte del nome o del titolo, senza distinzione tra maiuscole e minuscole.

- `match`, `order`, `direction`: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

### Chiavi di filtro

I filtri usano parametri di query `key.condition=value`, ad esempio `name.starts_with=order.` o `created_at.after=2026-10-01`. Per le condizioni di ogni tipo, vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | Il nome senza il prefisso `w:`. |
| `title` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Chiavi di ordinamento per `order`: `name`, `title`, `created_at`, `updated_at`. Il valore predefinito è `name`, in ordine crescente.

## Restituisce

- `data` (object[]): Gli [oggetti evento di workspace](/it/docs/api-reference/workspace-events/get/) di questa pagina.

- `total_records` (integer): Numero di definizioni che corrispondono alla query.

- `next_page_url` (string | null): Percorso della pagina successiva, oppure `null` sull’ultima pagina. Contiene solo `page` e `limit`; quando lo segui, aggiungi di nuovo la ricerca e i filtri.

- `previous_page_url` (string | null): Percorso della pagina precedente, oppure `null` sulla prima pagina.

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

---
Fonte: https://emailit.com/it/docs/api-reference/workspace-events/list/

## Elimina un evento di workspace — DELETE /workspace/events/{id}

> Elimina la definizione di un evento di workspace. Gli eventi memorizzati vengono conservati, e i nuovi eventi di quel tipo vengono rifiutati.

# Elimina un evento di workspace

Elimina la definizione di un evento di workspace. Richiede una chiave API con il permesso `full`.

Gli eventi già memorizzati con questo tipo vengono conservati, nel log degli eventi e sui contatti. I nuovi eventi di questo tipo vengono rifiutati con `422` finché non lo definisci di nuovo. I webhook che sottoscrivono il tipo mantengono la sottoscrizione.

`DELETE /workspace/events/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della definizione (`etp_…`), il suo nome o il suo tipo di evento (`w:…`).

## Restituisce

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

- `id` (string): L’ID della definizione eliminata.

- `name` (string): Il suo nome.

- `type` (string): Il suo tipo di evento, `w:` seguito dal nome.

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

Restituisce `404` se nessuna definizione corrisponde.

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

---
Fonte: https://emailit.com/it/docs/api-reference/workspace-events/delete/