Eventi

Invia eventi di workspace e personalizzati, e leggi il flusso di eventi alla base dei webhook: consegne, bounce, aperture e altro.

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

POST/events
POST/events/batch
GET/events
GET/events/{id}

Invia un evento

Registra un evento di workspace (w:<name>) o un evento personalizzato (c:<name>). Funziona con le chiavi API con il permesso full o events. Per sapere quale usare e quando, vedi Tracciamento degli eventi. Gli eventi sono inclusi nei piani Pro, Business e Custom, con un massimo di 100 tipi di evento con Pro e 1000 con Business.

Un evento di workspace deve prima essere definito. Le sue properties vengono controllate rispetto alla definizione.
Un evento personalizzato non richiede una definizione. Le sue properties possono essere un qualsiasi oggetto JSON.

Gli eventi di sistema come email.delivered vengono registrati da Emailit e non si possono inviare. Per registrare molti eventi con una sola chiamata, usa Invia eventi in batch.

POST/events

Parametri del corpo

typestringobbligatorio

w:<name> per un evento di workspace o c:<name> per un evento personalizzato, ad esempio c:order.completed. Il nome ha da 1 a 100 caratteri tra lettere, cifre, ., - o _, e inizia con una lettera o una cifra.

propertiesobject

I dati dell’evento. Predefinito {}.

Eventi di workspace: solo le proprietà della definizione, ciascuna con il suo tipo. Le proprietà obbligatorie devono essere presenti, null lascia vuota una proprietà facoltativa, e le date vengono memorizzate in ISO 8601 in UTC. Vedi Tipi di proprietà.
Eventi personalizzati: qualsiasi oggetto JSON, fino a 32 KB e 8 livelli di profondità.

emailstring

L’indirizzo email della persona a cui si riferisce l’evento. Se un contatto ha questo indirizzo, l’evento viene attribuito a quel contatto. Se nessun contatto lo ha, l’indirizzo viene comunque memorizzato, e l’evento compare nell’attività del contatto quando lo crei.

contact_idstring

L’ID di un contatto esistente (con_…). Ha la precedenza su email. Un ID che non corrisponde a un contatto del workspace restituisce 422.

anonymous_idstring

Un tuo identificativo per un visitatore o un dispositivo, fino a 128 caratteri, per gli eventi che non puoi ancora collegare a una persona.

occurred_atstring | integer

Quando è avvenuto: una data e ora ISO 8601 o un timestamp in millisecondi. Predefinito: adesso. Può essere nel passato, ma non più di 24 ore nel futuro.

contextobject

Dove è avvenuto l’evento: page (url, path, title, referrer, search), campaign (source, medium, name, term, content), locale e timezone. Le chiavi sconosciute vengono scartate e i valori lunghi vengono accorciati.

I contatti vengono solo cercati, mai creati. Emailit non memorizza gli indirizzi IP insieme agli eventi.

Restituisce

Restituisce 201 Created con l’evento: object, id, type, created_at e data. data.object contiene ciò che è stato memorizzato:

objectstring

workspace_event o custom_event.

namestring

Il nome dell’evento senza il prefisso.

propertiesobject

Le proprietà convalidate.

contactobject | null

id ed email del contatto a cui appartiene l’evento. id è null quando è nota solo l’email. null se non hai inviato nessuno dei due.

anonymous_idstring | null

L’anonymous_id che hai inviato.

occurred_atstring

Quando è avvenuto, in UTC.

sourcestring

api per questo endpoint. Gli eventi dello script di tracciamento hanno js, e gli eventi di test inviati dal pannello hanno dashboard.

contextobject

Il contesto memorizzato. Omesso quando non ce n’è uno.

Una chiave API con il permesso events non può leggere dati, quindi riceve l’evento senza data, che contiene il contatto trovato tramite l’email.

Stato	Quando
`400`	Il corpo non è un oggetto JSON.
`403`	Il permesso della chiave API non è né `full` né `events`, oppure il piano non include gli eventi di workspace e personalizzati: con Pay as you go, `error` è `plan_required` e `required_plan` è `pro`. Non viene memorizzato nulla.
`422`	L’evento non è valido. `errors` ha come chiave il campo, ad esempio `type` o `properties.total`, e `message` ripete il primo problema. Viene restituito anche per un evento `w:` non definito, per un `contact_id` che non corrisponde a un contatto e per un tipo che il workspace non ha mai inviato prima, quando usa già il numero di tipi di evento previsto dal piano (100 con Pro, 1000 con Business).
`429`	Troppe richieste in un minuto, oppure il workspace ha raggiunto il limite giornaliero di uso corretto per gli eventi di workspace e personalizzati (`code`: `events_daily_limit`). Non viene memorizzato nulla. Riprova dopo il numero di secondi indicato nell’header `retry-after`.

POST/events

Terminal

curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'c:order.completed',
    email: 'jane@example.com',
    properties: { order_id: '1001', total: 59.9, currency: 'EUR' },
    occurred_at: '2026-10-19T09:30:00Z',
  }),
});
const event = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "type": "c:order.completed",
        "email": "jane@example.com",
        "properties": {"order_id": "1001", "total": 59.9, "currency": "EUR"},
        "occurred_at": "2026-10-19T09:30:00Z",
    },
)
event = r.json()

PHP

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

$response = $client->post('events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'type' => 'c:order.completed',
        'email' => 'jane@example.com',
        'properties' => ['order_id' => '1001', 'total' => 59.9, 'currency' => 'EUR'],
        'occurred_at' => '2026-10-19T09:30:00Z',
    ],
]);
$event = json_decode($response->getBody(), true);

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00",
  "data": {
    "object": {
      "object": "custom_event",
      "name": "order.completed",
      "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
      "contact": { "id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "email": "jane@example.com" },
      "anonymous_id": null,
      "occurred_at": "2026-10-19T09:30:00.000Z",
      "source": "api"
    }
  }
}

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00"
}

JSON

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

JSON

{
  "error": "properties.segment must be a string",
  "message": "properties.segment must be a string",
  "errors": {
    "properties.segment": ["must be a string"]
  }
}

JSON

{
  "error": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "message": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "errors": {
    "type": ["w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier)."]
  }
}

Invia eventi in batch

Registra fino a 100 eventi di workspace e personalizzati in una sola richiesta, ad esempio quando il tuo backend sincronizza gli ordini a intervalli programmati. Funziona con le chiavi API con il permesso full o events, nei piani Pro, Business e Custom.

Il batch è tutto o niente. Se un evento non è valido, non ne viene memorizzato nessuno, e la risposta elenca ogni problema in base alla posizione dell’evento nell’elenco.

POST/events/batch

Parametri del corpo

eventsobject[]obbligatorio

Da 1 a 100 eventi. Ognuno accetta gli stessi campi di Invia un evento: type, properties, email, contact_id, anonymous_id, occurred_at e context.

Restituisce

Restituisce 201 Created con gli eventi memorizzati in data, nell’ordine in cui li hai inviati. Ogni elemento ha object (event), id, type e created_at. Usa Recupera un evento per leggerne uno con il suo data.

Stato	Quando
`400`	`events` manca, è vuoto o ha più di 100 elementi.
`403`	Il permesso della chiave API non è né `full` né `events`, oppure il piano non include gli eventi di workspace e personalizzati: con Pay as you go, `error` è `plan_required` e `required_plan` è `pro`. Non viene memorizzato nulla.
`422`	Almeno un evento non è valido. Non viene memorizzato nulla. `errors` ha come chiave `events.<index>.<field>`, ad esempio `events.3.properties.total`, contando da 0, e `message` ripete il primo problema. Un evento di un tipo che il workspace non ha mai inviato prima non è valido quando il workspace usa già il numero di tipi di evento previsto dal piano (100 con Pro, 1000 con Business).
`429`	Troppe richieste in un minuto, oppure il batch porterebbe il workspace oltre il limite giornaliero di uso corretto per gli eventi di workspace e personalizzati (`code`: `events_daily_limit`). Non viene memorizzato nulla. Riprova dopo il numero di secondi indicato nell’header `retry-after`.

POST/events/batch

Terminal

curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } },
      { "type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": { "segment": "b2b" } }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      { type: 'c:order.completed', email: 'jane@example.com', properties: { order_id: '1001', total: 59.9 } },
      { type: 'c:order.completed', email: 'omar@example.com', properties: { order_id: '1002', total: 18 } },
      { type: 'w:customer.type', contact_id: 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', properties: { segment: 'b2b' } },
    ],
  }),
});
const { data } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events/batch",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "events": [
            {"type": "c:order.completed", "email": "jane@example.com", "properties": {"order_id": "1001", "total": 59.9}},
            {"type": "c:order.completed", "email": "omar@example.com", "properties": {"order_id": "1002", "total": 18}},
            {"type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": {"segment": "b2b"}},
        ]
    },
)
stored = r.json()["data"]

PHP

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

$response = $client->post('events/batch', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'events' => [
            ['type' => 'c:order.completed', 'email' => 'jane@example.com', 'properties' => ['order_id' => '1001', 'total' => 59.9]],
            ['type' => 'c:order.completed', 'email' => 'omar@example.com', 'properties' => ['order_id' => '1002', 'total' => 18]],
            ['type' => 'w:customer.type', 'contact_id' => 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', 'properties' => ['segment' => 'b2b']],
        ],
    ],
]);
$stored = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    { "object": "event", "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Sa1XcP4uW8rMyB6fGjK0nT", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Td5ZeQ7vX2sNzC9hHkL3pU", "type": "w:customer.type", "created_at": "2026-10-19T09:30:02.114000+00:00" }
  ]
}

JSON

{
  "error": "events.1.email must be a valid email address",
  "message": "events.1.email must be a valid email address",
  "errors": {
    "events.1.email": ["must be a valid email address"],
    "events.2.properties.segment": ["must be a string"]
  }
}

Elenca gli eventi

Restituisce gli eventi del workspace, a partire dal più recente. Ogni consegna webhook è costruita a partire da uno di questi eventi, quindi puoi usare questo endpoint per recuperare gli eventi che il tuo endpoint non ha ricevuto. Richiede una chiave API con il permesso full.

GET/events

Parametri di query

pageinteger

Numero di pagina, a partire da 1. Predefinito 1. Le pagine oltre i 2500 eventi ((page - 1) × limit > 2500) restituiscono 422.

limitinteger

Eventi per pagina, da 1 a 100. Predefinito 100.

typestring

Il tipo di evento, o un elenco di tipi separati da virgole, ad esempio email.delivered,email.bounced. Gli eventi di workspace e personalizzati mantengono il prefisso, ad esempio c:order.completed. Vedi Tipi di evento.

scopestring

Solo gli eventi di questi ambiti, separati da virgole: system (eventi registrati da Emailit, come email.delivered), workspace (eventi definiti nel workspace, w:<name>) e custom (eventi personalizzati, c:<name>). Ad esempio scope=workspace,custom. Predefinito: tutti gli ambiti. Un ambito sconosciuto restituisce 400.

include_databoolean

Imposta true per includere il payload data di ogni evento. Predefinito false, che restituisce solo object, id, type e created_at.

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.

Filtri e ordinamento

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

Chiave	Tipo	Condizioni	Note
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Chiavi di ordinamento

Passa in order una di queste chiavi e in direction il valore asc o desc: type, created_at

Senza un filtro created_at, l’elenco copre solo gli ultimi 2 giorni. Per andare più indietro, aggiungine uno, ad esempio created_at.after=2026-09-01T00:00:00Z. Gli eventi più vecchi restano disponibili finché li mantiene la conservazione dei dati del piano.

Restituisce

Restituisce 200 OK con gli eventi in data, più next_page_url e previous_page_url (null alle due estremità). Gli URL delle pagine mantengono type, scope, limit e include_data.

Restituisce 422 con code: "events_offset_too_large" quando la pagina è troppo profonda. Invece di andare oltre con le pagine, restringi l’intervallo di date o i tipi.

GET/events

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const events = await emailit.events.list({ type: 'email.delivered' });

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

events = client.events.list({"type": "email.delivered"})

PHP

$emailit = Emailit::client('your_api_key');

$events = $emailit->events()->list(['type' => 'email.delivered']);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

events = client.events.list(type: "email.delivered")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

events, err := client.Events.List(&emailit.ListEventsRequest{Type: "email.delivered"})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let events = emailit.events.list(Some(emailit::types::ListEventsParams { r#type: Some("email.delivered".into()), ..Default::default() })).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject events = emailit.events().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var events = emailit.Events.List(new EventListOptions { Type = "email.delivered" });

PHP

use Emailit\Laravel\Facades\Emailit;

$events = Emailit::events()->list(['type' => 'email.delivered']);

Terminal

curl -X GET "https://api.emailit.com/v2/events?type=email.delivered" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered",
  "previous_page_url": null
}

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "data": {
        "object": {
          "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
          "object": "email",
          "from": "hello@acme.com",
          "to": "ada@example.com",
          "subject": "Your order has shipped",
          "status": "delivered",
          "meta": { "order_id": "1042" },
          "updated_at": "2026-10-01T10:02:14.307000+00:00",
          "created_at": "2026-10-01T10:02:11.583000+00:00"
        }
      },
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered&include_data=true",
  "previous_page_url": null
}

JSON

{
  "error": "Page is too deep. Narrow the type or date filter, or open an earlier page.",
  "code": "events_offset_too_large"
}

Recupera un evento

Restituisce un evento con il suo payload data completo. L’id è lo stesso valore che i webhook inviano come event_id, quindi puoi consultare qualsiasi evento che hai ricevuto. Richiede una chiave API con il permesso full.

GET/events/:id

Parametri di percorso

idstringObbligatorio

L’ID dell’evento, ad esempio evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a.

Restituisce

Restituisce 200 OK con l’evento: object (event), id, type, data e created_at. data.object ha la stessa forma del payload webhook per quel tipo; vedi i tipi di evento dei webhook.

Per gli eventi di workspace (w:) e personalizzati (c:), data.object contiene object (workspace_event o custom_event), name, properties, contact, anonymous_id, occurred_at, source, identity_verified per gli eventi dello script di tracciamento che indicano un contatto e, quando presente, context. Vedi Invia un evento.

Restituisce 404 con error: "Event not found" se l’ID non esiste nel workspace.

GET/events/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const event = await emailit.events.get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

PHP

$emailit = Emailit::client('your_api_key');

$event = $emailit->events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

event, err := client.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let event = emailit.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a").await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject event = emailit.events().get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var ev = emailit.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

PHP

use Emailit\Laravel\Facades\Emailit;

$event = Emailit::events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Terminal

curl https://api.emailit.com/v2/events/evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "event",
  "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
      "object": "email",
      "from": "hello@acme.com",
      "to": "ada@example.com",
      "subject": "Your order has shipped",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T10:02:14.307000+00:00",
      "created_at": "2026-10-01T10:02:11.583000+00:00"
    }
  },
  "created_at": "2026-10-01T10:02:15.912000+00:00"
}

JSON

{
  "error": "Event not found"
}