# Eventi di workspace

> Definisci gli eventi di workspace e il tipo di ogni proprietà, così ogni sistema che li invia resta coerente. Include i tipi di proprietà, la convalida e la modifica di una definizione.

Un evento di workspace è un evento che il workspace dichiara prima che qualcuno lo invii: il nome, un titolo facoltativo e le proprietà che contiene, ciascuna con un tipo. Gli eventi di quel tipo si inviano come `w:<name>`, ed Emailit rifiuta quelli che non corrispondono. Questa pagina spiega come definirli e come funziona la convalida.

Se non vuoi dichiarare una struttura, invia invece un [evento personalizzato](/it/docs/events/#three-scopes-of-events) (`c:<name>`). Gli eventi di workspace e gli eventi personalizzati sono inclusi nei piani Pro, Business e Custom.

## Definisci un evento di workspace

**Pannello**

  1. **Apri la scheda Workspace events.** Vai a **Email API → Events**, seleziona la scheda **Workspace events**, poi **Define workspace event**.

  2. **Dai un nome all’evento.** Compila il campo **Name**, ad esempio con `customer.type`. L’evento si invia come `w:customer.type`. Se vuoi, aggiungi un **Title**, mostrato nelle cronologie e nei selettori, e una **Description** per il team.

  3. **Aggiungi le proprietà.** Seleziona **Add property** per ogni valore che chi invia deve o può includere. Dai un nome alla proprietà, scegli il **Type** e attiva **Required** se ogni evento deve contenerla. Titolo e descrizione sono facoltativi.

  4. **Crea l’evento.** Seleziona **Create**. Per provarlo, seleziona **Send test** sulla definizione: si apre **Send event** con l’evento già scelto.

**API**

  Chiama [Crea un evento di workspace](/it/docs/api-reference/workspace-events/create/) con una chiave API con **Full Access**:

```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",
    "properties": [
      { "name": "segment", "type": "string", "required": true },
      { "name": "since", "type": "date" }
    ]
  }'
```

Poi invialo come qualsiasi altro evento, con lo script di tracciamento o con l’API:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "w:customer.type", "email": "jane@example.com", "properties": { "segment": "b2b", "since": "2026-10-01" } }'
```

## Tipi di proprietà

| Tipo | Accetta | Salvato come |
| --- | --- | --- |
| `string` | Una stringa JSON, fino a 2000 caratteri. | La stringa |
| `number` | Un numero JSON. I numeri tra virgolette, come `"42"`, vengono rifiutati. | Il numero |
| `date` | Una data ISO 8601 (`2026-10-01`) o una data e ora (`2026-10-01T12:00:00Z`), oppure un timestamp in millisecondi. Gli anni prima del 1900 vengono rifiutati. | Una data e ora ISO 8601 in UTC |
| `boolean` | `true` o `false`. | Il booleano |

## Come vengono controllati gli eventi

Quando arriva un evento `w:`, Emailit confronta le sue `properties` con la definizione:

- Ogni proprietà deve essere nella definizione. Le proprietà sconosciute vengono rifiutate, così un errore di battitura non passa inosservato.
- Le proprietà obbligatorie devono essere presenti e non `null`.
- Una proprietà facoltativa si può omettere, oppure inviare come `null` per indicare che è vuota.
- Ogni valore deve corrispondere al suo tipo.

Viene rifiutato anche un evento `w:` il cui nome non è definito. L’API risponde con `422` e ogni problema indicato con il suo percorso, ad esempio `properties.since`. Lo script di tracciamento scarta gli eventi non validi e, con il [debug](/it/docs/events/tracking-script/#debug) attivo, ne registra il motivo.

## Modifica o elimina una definizione

Nella scheda **Workspace events**, seleziona **Edit** o **Delete** su una definizione. Con l’API, usa [Aggiorna un evento di workspace](/it/docs/api-reference/workspace-events/update/) ed [Elimina un evento di workspace](/it/docs/api-reference/workspace-events/delete/).

- Una definizione controlla solo i nuovi eventi. Gli eventi già salvati mantengono le proprietà che avevano.
- Modificare le proprietà sostituisce l’intero elenco. I sistemi che inviano ancora una proprietà rimossa ricevono errori, quindi aggiornali prima o contemporaneamente.
- Rinominare cambia il tipo da inviare. Gli eventi salvati mantengono il vecchio tipo, e i nuovi eventi con il vecchio nome vengono rifiutati.
- L’eliminazione mantiene gli eventi salvati, e i nuovi eventi di quel tipo vengono rifiutati finché non lo definisci di nuovo.

## Limiti

Un workspace può definire tanti eventi di workspace quanti sono i [tipi di evento](/it/docs/events/#limits) del suo piano: 100 con Pro e 1000 con Business, senza limiti con Custom. Uno in più restituisce `422` con `code` `workspace_events_limit`. Ogni evento di workspace ha un massimo di 50 proprietà. I nomi hanno al massimo 100 caratteri, i nomi delle proprietà 64, i titoli 120 e le descrizioni 1000.

## Vedi anche

  - [Tracciamento degli eventi](/it/docs/events/): Ambiti, nomi e dove finiscono gli eventi.
  - [API degli eventi di workspace](/it/docs/api-reference/workspace-events/): Crea, elenca, aggiorna ed elimina le definizioni.

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