Workspace-Events

Workspace-Events und die Typen ihrer Eigenschaften definieren, damit die gesendeten w:-Events geprüft werden.

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

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

Workspace-Event erstellen

Definiert ein Workspace-Event: einen Namen und die Eigenschaften, die jedes Event dieses Typs mitbringt, jeweils mit einem Typ. Anschließend senden Sie es als w:<name>, und Emailit lehnt Events ab, die nicht passen. Erfordert einen API-Schlüssel mit dem Scope full.

Workspace-Events sind in den Tarifen Pro, Business und Custom enthalten. Ein Workspace kann so viele definieren, wie sein Tarif Event-Typen umfasst: 100 bei Pro und 1.000 bei Business, ohne Limit bei Custom. Eigene Events (c:<name>) brauchen keine Definition. Siehe Workspace-Events.

POST/workspace/events

Body-Parameter

namestringerforderlich

Der Name des Events, zum Beispiel customer.type: 1 bis 100 Buchstaben, Ziffern, ., - oder _, beginnend mit einem Buchstaben oder einer Ziffer. Sie können ihn auch mit Präfix senden (w:customer.type); das Präfix wird entfernt. Muss im Workspace eindeutig sein.

titlestring | null

Ein lesbarer Name, den die Weboberfläche anzeigt, bis zu 120 Zeichen.

descriptionstring | null

Notiz für Ihr Team, bis zu 1.000 Zeichen.

propertiesobject[]

Bis zu 50 Eigenschaftsdefinitionen. Standardwert: [], das heißt, Events dieses Typs haben keine Eigenschaften. Jede Definition hat:

name (erforderlich): 1 bis 64 Buchstaben, Ziffern, - oder _, beginnend mit einem Buchstaben oder einer Ziffer. Punkte sind nicht erlaubt, weil Webhook-Filter und Vorlagen mit Punkten auf verschachtelte Werte zugreifen. Namen müssen innerhalb der Definition eindeutig sein.
type (erforderlich): string, number, date oder boolean, in beliebiger Groß-/Kleinschreibung.
title: eine Beschriftung, bis zu 120 Zeichen.
description: bis zu 1.000 Zeichen.
required: true, wenn jedes Event die Eigenschaft enthalten muss. Standardwert: false.

Rückgabe

Gibt 201 Created mit dem Workspace-Event-Objekt zurück.

Status	Wann
`403`	Der API-Schlüssel hat nicht den Scope `full`, oder der Workspace ist im Tarif Pay as you go: `error` ist `plan_required` und `required_plan` ist `pro`.
`409`	Ein Workspace-Event mit diesem Namen existiert bereits. `errors.name` weist darauf hin.
`422`	Ein Feld ist ungültig: `errors` ist nach seinem Pfad geschlüsselt, etwa `name` oder `properties.1.type`, und `message` wiederholt das erste Problem. Wird auch mit `code: "workspace_events_limit"` zurückgegeben, wenn der Workspace bereits so viele Workspace-Events hat, wie sein Tarif erlaubt, und für einen Namen, der mit `c:` beginnt.

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

Workspace-Event abrufen

Ruft die Definition eines Workspace-Events ab: Name, Titel und die Eigenschaften, an die sich Absender halten müssen. Erfordert einen API-Schlüssel mit dem Scope full.

GET/workspace/events/{id}

Pfadparameter

idstringerforderlich

Die ID der Definition (etp_…), ihr Name (customer.type) oder ihr Event-Typ (w:customer.type). Kodieren Sie das Zeichen : für die URL, wenn Ihr Client das nicht tut.

Rückgabe

Gibt das Workspace-Event-Objekt zurück.

objectstring

Immer workspace_event.

idstring

ID der Definition mit dem Präfix etp_.

namestring

Der Name des Events, ohne das Präfix.

typestring

Der Typ, den Sie senden und nach dem Sie filtern: w: gefolgt vom Namen.

titlestring | null

Ein lesbarer Name, den die Weboberfläche statt des Typs anzeigt, zum Beispiel in der Aktivität eines Kontakts.

descriptionstring | null

Notiz für Ihr Team.

propertiesobject[]

Die Eigenschaften, die ein Event dieses Typs haben kann, jeweils mit:

name: dem Schlüssel in den properties des Events.
type: string, number, date oder boolean. Siehe Eigenschaftstypen.
title, description: optionalen Beschriftungen oder null.
required: ob jedes Event die Eigenschaft enthalten muss.

created_at, updated_atstring

Zeitstempel in UTC.

Gibt 404 mit error: "Workspace event not found" zurück, wenn keine Definition passt.

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

Workspace-Event aktualisieren

Aktualisiert die übergebenen Felder und lässt die übrigen unverändert. Erfordert einen API-Schlüssel mit dem Scope full.

Die Definition prüft nur neue Events. Bereits gespeicherte Events behalten ihren Typ und ihre Eigenschaften. Nach einer Änderung können ältere Events daher Eigenschaften haben, die die Definition nicht mehr aufführt.

properties ersetzt die gesamte Liste. Um eine Eigenschaft hinzuzufügen, senden Sie die aktuelle Liste und die neue Eigenschaft.
Eine Umbenennung ändert den Typ, den Sie senden. Unter dem alten Namen gespeicherte Events behalten ihn, und neue Events mit dem alten Namen werden abgelehnt, sofern Sie ihn nicht erneut definieren.

POST/workspace/events/{id}

Pfadparameter

idstringerforderlich

Die ID der Definition (etp_…), ihr Name oder ihr Event-Typ (w:…).

Body-Parameter

namestring

Ein neuer Name, mit denselben Regeln wie beim Erstellen.

titlestring | null

Bis zu 120 Zeichen. null oder ein leerer String löscht den Titel.

descriptionstring | null

Bis zu 1.000 Zeichen. null oder ein leerer String löscht die Beschreibung.

propertiesobject[]

Die neue Liste der Eigenschaften, bis zu 50, wie beim Erstellen. [] entfernt alle Eigenschaften.

Rückgabe

Gibt das aktualisierte Workspace-Event-Objekt zurück.

Status	Wann
`404`	Keine Definition passt zu `id`.
`409`	Ein anderes Workspace-Event hat bereits den neuen Namen.
`422`	Ein Feld ist ungültig: `errors` ist nach seinem Pfad geschlüsselt, und `message` wiederholt das erste Problem.

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

Workspace-Events auflisten

Gibt die Event-Definitionen des Workspaces zurück, nach Namen sortiert. Erfordert einen API-Schlüssel mit dem Scope full.

GET/workspace/events

Query-Parameter

pageintegerStandardwert: 1

Seitennummer, beginnend bei 1.

limitintegerStandardwert: 100

Definitionen pro Seite, von 1 bis 250.

searchstring

Abgleich mit einem Teil des Namens oder des Titels, ohne Beachtung der Groß-/Kleinschreibung.

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.

Filterschlüssel

Filter verwenden Query-Parameter der Form key.condition=value, zum Beispiel name.starts_with=order. oder created_at.after=2026-10-01. Die Bedingungen je Typ finden Sie unter Filtern.

Schlüssel	Typ	Hinweise
`name`	string	Der Name ohne das Präfix `w:`.
`title`	string
`created_at`	date
`updated_at`	date

Sortierschlüssel für order: name, title, created_at, updated_at. Standardmäßig wird aufsteigend nach name sortiert.

Rückgabe

dataobject[]

Workspace-Event-Objekte auf dieser Seite.

total_recordsinteger

Anzahl der Definitionen, die der Abfrage entsprechen.

next_page_urlstring | null

Pfad der nächsten Seite oder null auf der letzten Seite. Er enthält nur page und limit; fügen Sie Ihre Suche und Ihre Filter wieder hinzu, wenn Sie ihm folgen.

previous_page_urlstring | null

Pfad der vorherigen Seite oder null auf der ersten Seite.

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
}

Workspace-Event löschen

Löscht die Definition eines Workspace-Events. Erfordert einen API-Schlüssel mit dem Scope full.

Bereits mit diesem Typ gespeicherte Events bleiben erhalten, im Event-Log und bei den Kontakten. Neue Events dieses Typs werden mit 422 abgelehnt, bis Sie ihn erneut definieren. Webhooks, die den Typ abonniert haben, behalten das Abonnement.

DELETE/workspace/events/{id}

Pfadparameter

idstringerforderlich

Die ID der Definition (etp_…), ihr Name oder ihr Event-Typ (w:…).

Rückgabe

objectstring

Immer workspace_event.

idstring

ID der gelöschten Definition.

namestring

Ihr Name.

typestring

Ihr Event-Typ, w: gefolgt vom Namen.

deletedboolean

Immer true.

Gibt 404 zurück, wenn keine Definition passt.

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
}