Eventi di workspace

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

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

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.

POST/workspace/events

Parametri del corpo

namestringobbligatorio

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.

titlestring | null

Un nome leggibile mostrato nel pannello, fino a 120 caratteri.

descriptionstring | null

Nota per il team, fino a 1000 caratteri.

propertiesobject[]

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.

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

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

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

idstringobbligatorio

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.

objectstring

Sempre workspace_event.

idstring

ID della definizione, con prefisso etp_.

namestring

Il nome dell’evento, senza il prefisso.

typestring

Il tipo da inviare e su cui filtrare: w: seguito dal nome.

titlestring | null

Un nome leggibile, mostrato nel pannello al posto del tipo, ad esempio nell’attività di un contatto.

descriptionstring | null

Nota per il team.

propertiesobject[]

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à.
title, description: etichette facoltative, oppure null.
required: indica se ogni evento deve includerla.

created_at, updated_atstring

Timestamp in UTC.

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

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

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

idstringobbligatorio

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

Parametri del corpo

namestring

Un nuovo nome, con le stesse regole valide in creazione.

titlestring | null

Fino a 120 caratteri. null o una stringa vuota lo cancellano.

descriptionstring | null

Fino a 1000 caratteri. null o una stringa vuota la cancellano.

propertiesobject[]

Il nuovo elenco di proprietà, fino a 50, come in creazione. [] rimuove tutte le proprietà.

Restituisce

Restituisce l’oggetto evento di workspace 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.

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

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

pageintegerpredefinito: 1

Numero della pagina, a partire da 1.

limitintegerpredefinito: 100

Definizioni per pagina, da 1 a 250.

searchstring

Corrispondenza su una parte del nome o del titolo, senza distinzione tra maiuscole e minuscole.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

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.

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

dataobject[]

Gli oggetti evento di workspace di questa pagina.

total_recordsinteger

Numero di definizioni che corrispondono alla query.

next_page_urlstring | 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_urlstring | null

Percorso della pagina precedente, oppure null sulla prima pagina.

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
}

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

idstringobbligatorio

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

Restituisce

objectstring

Sempre workspace_event.

idstring

L’ID della definizione eliminata.

namestring

Il suo nome.

typestring

Il suo tipo di evento, w: seguito dal nome.

deletedboolean

Sempre true.

Restituisce 404 se nessuna definizione corrisponde.

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
}