Invia eventi dal tuo backend

Invia gli eventi dai tuoi server per tutto ciò che non deve dipendere dal browser del visitatore, come ordini, pagamenti, modifiche agli abbonamenti o eventi da un back office. Questa pagina mostra come inviare un evento, come inviarne molti e come gestire gli errori.

Prima di iniziare

• L’invio di eventi è incluso nei piani Pro, Business e Custom. Un workspace Pro può usare 100 tipi di evento e un workspace Business 1000. Vedi Limiti.
• Crea una chiave API con il permesso Events Only in Email API›API Keys. Può inviare eventi e nient’altro: non può leggere i tuoi dati, gestire le definizioni degli eventi né inviare email. Funziona anche una chiave con Full Access. Vedi Chiavi API.
• Per inviare eventi di workspace, prima definiscili. Gli eventi personalizzati non richiedono configurazione.

Invia un evento

Chiama Invia un evento con il type dell’evento, le sue properties e la persona a cui si riferisce:

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

• Il campo email collega l’evento al contatto con quell’indirizzo. Se conosci già l’ID del contatto, invia invece contact_id.
• Il campo occurred_at indica quando è avvenuto l’evento, ad esempio quando invii eventi da una coda. Omettilo per usare l’ora attuale.
• La risposta è 201 con l’evento salvato e il suo ID evt_. Una chiave di soli eventi riceve l’evento senza data.

Invia più eventi insieme

Invia eventi in batch accetta fino a 100 eventi in una richiesta, ed è adatto a importazioni e sincronizzazioni programmate:

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

Un batch è tutto o niente: se un evento non è valido, non ne viene salvato nessuno. La risposta 422 elenca ogni problema sotto events.<index>, così puoi correggere o togliere quegli eventi e inviare di nuovo il batch.

Gestisci gli errori

Gli eventi non hanno una chiave di idempotenza, quindi ritentare una richiesta andata a buon fine salva l’evento due volte. Metti un tuo ID nelle proprietà, come order_id, così chi legge gli eventi può riconoscere i duplicati.

Controlla che gli eventi arrivino

Apri Email API›Events. La scheda Log elenca in alto i nuovi eventi; imposta Scope su Custom o Workspace per nascondere gli eventi di sistema. Seleziona un evento per vederne le proprietà, il contatto a cui appartiene e la provenienza. Gli eventi collegati a un contatto compaiono anche nella sezione Activity log del contatto.

Vedi anche