Events

Workspace-Events und eigene Events senden und den Event-Stream hinter den Webhooks lesen: Zustellungen, Bounces, Öffnungen und mehr.

Basis-URLhttps://api.emailit.com/v2Authentifizierung Fehler Rate Limits

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

Event senden

Erfasst ein Workspace-Event (w:<name>) oder ein eigenes Event (c:<name>). Funktioniert mit API-Schlüsseln mit dem Scope full oder events. Wann Sie welches verwenden, erfahren Sie unter Event-Tracking. Events sind in den Tarifen Pro, Business und Custom enthalten, mit bis zu 100 Event-Typen bei Pro und 1.000 bei Business.

Ein Workspace-Event muss zuerst definiert werden. Seine properties werden mit der Definition abgeglichen.
Ein eigenes Event braucht keine Definition. Seine properties können ein beliebiges JSON-Objekt sein.

System-Events wie email.delivered erfasst Emailit, und sie lassen sich nicht senden. Um viele Events mit einem Aufruf zu erfassen, verwenden Sie Events gesammelt senden.

POST/events

Body-Parameter

typestringerforderlich

w:<name> für ein Workspace-Event oder c:<name> für ein eigenes Event, zum Beispiel c:order.completed. Der Name besteht aus 1 bis 100 Buchstaben, Ziffern, ., - oder _ und beginnt mit einem Buchstaben oder einer Ziffer.

propertiesobject

Die Daten des Events. Standardwert: {}.

Workspace-Events: nur die Eigenschaften der Definition, jeweils mit ihrem Typ. Erforderliche Eigenschaften müssen vorhanden sein, null lässt eine optionale leer, und Datumsangaben werden als ISO 8601 in UTC gespeichert. Siehe Eigenschaftstypen.
Eigene Events: ein beliebiges JSON-Objekt, bis zu 32 KB groß und bis zu 8 Ebenen tief.

emailstring

Die E-Mail-Adresse der Person, um die es bei dem Event geht. Hat ein Kontakt diese Adresse, wird das Event diesem Kontakt zugeordnet. Hat kein Kontakt sie, wird die Adresse trotzdem gespeichert, und das Event erscheint in der Aktivität des Kontakts, sobald Sie ihn erstellen.

contact_idstring

Die ID eines bestehenden Kontakts (con_…). Hat Vorrang vor email. Eine ID, die zu keinem Kontakt im Workspace passt, gibt 422 zurück.

anonymous_idstring

Ihre eigene Kennung für einen Besucher oder ein Gerät, bis zu 128 Zeichen, für Events, die Sie noch keiner Person zuordnen können.

occurred_atstring | integer

Zeitpunkt des Geschehens: ein Datum mit Uhrzeit im Format ISO 8601 oder ein Zeitstempel in Millisekunden. Standardwert: jetzt. Darf in der Vergangenheit liegen, aber höchstens 24 Stunden in der Zukunft.

contextobject

Wo das Event stattfand: page (url, path, title, referrer, search), campaign (source, medium, name, term, content), locale und timezone. Unbekannte Schlüssel werden verworfen, lange Werte gekürzt.

Kontakte werden nur gesucht, nie erstellt. Emailit speichert zu Events keine IP-Adressen.

Rückgabe

Gibt 201 Created mit dem Event zurück: object, id, type, created_at und data. data.object enthält, was gespeichert wurde:

objectstring

workspace_event oder custom_event.

namestring

Der Name des Events ohne sein Präfix.

propertiesobject

Die validierten Eigenschaften.

contactobject | null

id und email des Kontakts, zu dem das Event gehört. id ist null, wenn nur die E-Mail-Adresse bekannt ist. null, wenn Sie keins von beiden gesendet haben.

anonymous_idstring | null

Die anonymous_id, die Sie gesendet haben.

occurred_atstring

Zeitpunkt des Geschehens, in UTC.

sourcestring

api für diesen Endpunkt. Events aus dem Tracking-Skript haben js, und Test-Events aus der Weboberfläche haben dashboard.

contextobject

Der gespeicherte Kontext. Fehlt, wenn es keinen gibt.

Ein API-Schlüssel mit dem Scope events darf keine Daten lesen. Er erhält das Event daher ohne data zurück, das den per E-Mail-Adresse zugeordneten Kontakt enthält.

Status	Wann
`400`	Der Body ist kein JSON-Objekt.
`403`	Der Scope des API-Schlüssels ist weder `full` noch `events`, oder der Tarif enthält keine Workspace-Events und eigenen Events: Bei Pay as you go ist `error` `plan_required` und `required_plan` `pro`. Nichts wird gespeichert.
`422`	Das Event ist ungültig. `errors` ist nach Feld geschlüsselt, etwa `type` oder `properties.total`, und `message` wiederholt das erste Problem. Wird auch für ein nicht definiertes `w:`-Event zurückgegeben, für eine `contact_id`, die zu keinem Kontakt passt, und für einen Typ, den der Workspace noch nie gesendet hat, sobald er so viele Event-Typen nutzt, wie sein Tarif umfasst (100 bei Pro, 1.000 bei Business).
`429`	Zu viele Anfragen in einer Minute oder der Workspace hat sein tägliches Fair-Use-Limit für Workspace-Events und eigene Events erreicht (`code`: `events_daily_limit`). Nichts wird gespeichert. Versuchen Sie es nach der Anzahl Sekunden im Header `retry-after` erneut.

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

Events gesammelt senden

Erfasst bis zu 100 Workspace-Events und eigene Events mit einer Anfrage, zum Beispiel wenn Ihr Backend Bestellungen nach Zeitplan synchronisiert. Funktioniert mit API-Schlüsseln mit dem Scope full oder events, in den Tarifen Pro, Business und Custom.

Für den Batch gilt: alles oder nichts. Ist ein Event ungültig, wird keines gespeichert, und die Antwort listet jedes Problem nach der Position des Events in der Liste auf.

POST/events/batch

Body-Parameter

eventsobject[]erforderlich

1 bis 100 Events. Jedes akzeptiert dieselben Felder wie bei Event senden: type, properties, email, contact_id, anonymous_id, occurred_at und context.

Rückgabe

Gibt 201 Created mit den gespeicherten Events in data zurück, in der Reihenfolge, in der Sie sie gesendet haben. Jedes Element hat object (event), id, type und created_at. Mit Event abrufen lesen Sie ein Event mit seinem data.

Status	Wann
`400`	`events` fehlt, ist leer oder hat mehr als 100 Elemente.
`403`	Der Scope des API-Schlüssels ist weder `full` noch `events`, oder der Tarif enthält keine Workspace-Events und eigenen Events: Bei Pay as you go ist `error` `plan_required` und `required_plan` `pro`. Nichts wird gespeichert.
`422`	Mindestens ein Event ist ungültig. Nichts wird gespeichert. `errors` ist nach `events.<index>.<field>` geschlüsselt, zum Beispiel `events.3.properties.total`, gezählt ab 0, und `message` wiederholt das erste Problem. Ein Event eines Typs, den der Workspace noch nie gesendet hat, ist ungültig, sobald der Workspace so viele Event-Typen nutzt, wie sein Tarif umfasst (100 bei Pro, 1.000 bei Business).
`429`	Zu viele Anfragen in einer Minute oder der Batch würde den Workspace über sein tägliches Fair-Use-Limit für Workspace-Events und eigene Events bringen (`code`: `events_daily_limit`). Nichts wird gespeichert. Versuchen Sie es nach der Anzahl Sekunden im Header `retry-after` erneut.

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

Events auflisten

Gibt die Events in Ihrem Workspace zurück, die neuesten zuerst. Jede Webhook-Zustellung wird aus einem dieser Events erstellt. Mit diesem Endpunkt können Sie also Events nachholen, die Ihr Endpunkt verpasst hat. Erfordert einen API-Schlüssel mit dem Scope full.

GET/events

Query-Parameter

pageinteger

Seitennummer, beginnend bei 1. Standardwert 1. Seiten jenseits von 2.500 Events ((page - 1) × limit > 2500) geben 422 zurück.

limitinteger

Events pro Seite, von 1 bis 100. Standardwert 100.

typestring

Event-Typ oder kommagetrennte Liste von Typen, zum Beispiel email.delivered,email.bounced. Workspace-Events und eigene Events behalten ihr Präfix, zum Beispiel c:order.completed. Siehe Event-Typen.

scopestring

Nur Events dieser Scopes, kommagetrennt: system (Events, die Emailit erfasst, etwa email.delivered), workspace (im Workspace definierte Events, w:<name>) und custom (eigene Events, c:<name>). Zum Beispiel scope=workspace,custom. Standardwert: alle Scopes. Ein unbekannter Scope gibt 400 zurück.

include_databoolean

Setzen Sie den Wert auf true, um den Payload in data jedes Events einzuschließen. Standardwert false; dann werden nur object, id, type und created_at zurückgegeben.

matchstring

all (Standardwert) verlangt, dass alle Filter zutreffen. or trifft zu, wenn ein beliebiger Filter passt. Siehe Filtern und Sortieren.

orderstring

Sortierschlüssel für diese Liste. Siehe die Sortierschlüssel unten.

directionstring

asc oder desc.

Filter und Sortierung

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

Schlüssel	Typ	Bedingungen	Hinweise
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Sortierschlüssel

Übergeben Sie in order einen dieser Schlüssel und in direction den Wert asc oder desc: type, created_at

Ohne Filter auf created_at umfasst die Liste nur die letzten 2 Tage. Um weiter zurückzublicken, fügen Sie einen hinzu, zum Beispiel created_at.after=2026-09-01T00:00:00Z. Ältere Events sind so lange verfügbar, wie die Datenaufbewahrung Ihres Tarifs sie speichert.

Rückgabe

Gibt 200 OK mit den Events in data sowie next_page_url und previous_page_url zurück (am jeweiligen Ende null). Die Seiten-URLs behalten type, scope, limit und include_data bei.

Gibt 422 mit code: "events_offset_too_large" zurück, wenn die Seite zu tief liegt. Grenzen Sie den Zeitraum oder die Typen ein, statt weiterzublättern.

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

Event abrufen

Gibt ein Event mit seinem vollständigen Payload in data zurück. Die id ist derselbe Wert, den Webhooks als event_id senden. So können Sie jedes empfangene Event nachschlagen. Erfordert einen API-Schlüssel mit dem Scope full.

GET/events/:id

Pfadparameter

idstringErforderlich

ID des Events, zum Beispiel evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a.

Rückgabe

Gibt 200 OK mit dem Event zurück: object (event), id, type, data und created_at. data.object hat dieselbe Form wie im Webhook-Payload für diesen Typ; siehe die Referenz der Webhook-Events.

Bei Workspace-Events (w:) und eigenen Events (c:) enthält data.object die Felder object (workspace_event oder custom_event), name, properties, contact, anonymous_id, occurred_at, source, identity_verified bei Events aus dem Tracking-Skript, die einen Kontakt nennen, und, falls vorhanden, context. Siehe Event senden.

Gibt 404 mit error: "Event not found" zurück, wenn die ID in Ihrem Workspace nicht existiert.

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