# Workspace-Events API

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

Basis-URL: `https://api.emailit.com/v2`. Authentifizieren Sie sich mit `Authorization: Bearer <API key>`.

## Workspace-Event erstellen — POST /workspace/events

> Definieren Sie ein Workspace-Event und seine typisierten Eigenschaften. Events dieses Typs senden Sie dann mit dem Präfix w:, und Emailit gleicht sie mit der Definition ab.

# 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](/de/docs/events/workspace-events/).

`POST /workspace/events`

## Body-Parameter

- `name` (string, erforderlich): 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.

- `title` (string | null): Ein lesbarer Name, den die Weboberfläche anzeigt, bis zu 120 Zeichen.

- `description` (string | null): Notiz für Ihr Team, bis zu 1.000 Zeichen.

- `properties` (object[]): 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](/de/docs/api-reference/workspace-events/get/) 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. |

**Anfrage** `POST /workspace/events`

**cURL**

```bash
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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**201**

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

**403**

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

**409**

```json
{
  "error": "w:customer.type is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}
```

**422**

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

---
Quelle: https://emailit.com/de/docs/api-reference/workspace-events/create/

## Workspace-Event abrufen — GET /workspace/events/{id}

> Rufen Sie die Definition eines Workspace-Events per ID oder Name ab, mit ihren typisierten Eigenschaften.

# 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

- `id` (string, erforderlich): 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.

- `object` (string): Immer `workspace_event`.

- `id` (string): ID der Definition mit dem Präfix `etp_`.

- `name` (string): Der Name des Events, ohne das Präfix.

- `type` (string): Der Typ, den Sie senden und nach dem Sie filtern: `w:` gefolgt vom Namen.

- `title` (string | null): Ein lesbarer Name, den die Weboberfläche statt des Typs anzeigt, zum Beispiel in der Aktivität eines Kontakts.

- `description` (string | null): Notiz für Ihr Team.

- `properties` (object[]): 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](/de/docs/events/workspace-events/#property-types). - `title`, `description`: optionalen Beschriftungen oder `null`. - `required`: ob jedes Event die Eigenschaft enthalten muss.

- `created_at, updated_at` (string): Zeitstempel in UTC.

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

**Anfrage** `GET /workspace/events/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/workspace/events/w%3Acustomer.type \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```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**

```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**

```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);
```

**200**

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

**404**

```json
{
  "error": "Workspace event not found"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/workspace-events/get/

## Workspace-Event aktualisieren — POST /workspace/events/{id}

> Benennen Sie ein Workspace-Event um oder ändern Sie seinen Titel, seine Beschreibung oder seine Eigenschaften. Bereits gespeicherte Events ändern sich nicht.

# 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

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

## Body-Parameter

- `name` (string): Ein neuer Name, mit denselben Regeln wie beim [Erstellen](/de/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): Bis zu 120 Zeichen. `null` oder ein leerer String löscht den Titel.

- `description` (string | null): Bis zu 1.000 Zeichen. `null` oder ein leerer String löscht die Beschreibung.

- `properties` (object[]): Die neue Liste der Eigenschaften, bis zu 50, wie beim [Erstellen](/de/docs/api-reference/workspace-events/create/#body-parameters). `[]` entfernt alle Eigenschaften.

## Rückgabe

Gibt das aktualisierte [Workspace-Event-Objekt](/de/docs/api-reference/workspace-events/get/) 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. |

**Anfrage** `POST /workspace/events/{id}`

**cURL**

```bash
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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**200**

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

**409**

```json
{
  "error": "w:customer.segment is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/workspace-events/update/

## Workspace-Events auflisten — GET /workspace/events

> Listen Sie die Event-Definitionen des Workspaces nach Namen sortiert auf, mit ihren typisierten Eigenschaften, Suche und Filtern.

# 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

- `page` (integer): Seitennummer, beginnend bei 1.

- `limit` (integer): Definitionen pro Seite, von 1 bis 250.

- `search` (string): Abgleich mit einem Teil des Namens oder des Titels, ohne Beachtung der Groß-/Kleinschreibung.

- `match`, `order`, `direction`: siehe [Filtern und Sortieren](https://emailit.com/de/docs/api-reference/filtering/).

### 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](/de/docs/api-reference/filtering/).

| 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

- `data` (object[]): [Workspace-Event-Objekte](/de/docs/api-reference/workspace-events/get/) auf dieser Seite.

- `total_records` (integer): Anzahl der Definitionen, die der Abfrage entsprechen.

- `next_page_url` (string | 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_url` (string | null): Pfad der vorherigen Seite oder `null` auf der ersten Seite.

**Anfrage** `GET /workspace/events`

**cURL**

```bash
curl -G https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "search=customer"
```

**Node.js**

```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**

```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**

```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'];
```

**200**

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

---
Quelle: https://emailit.com/de/docs/api-reference/workspace-events/list/

## Workspace-Event löschen — DELETE /workspace/events/{id}

> Löschen Sie die Definition eines Workspace-Events. Gespeicherte Events bleiben erhalten, neue Events dieses Typs werden abgelehnt.

# 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

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

## Rückgabe

- `object` (string): Immer `workspace_event`.

- `id` (string): ID der gelöschten Definition.

- `name` (string): Ihr Name.

- `type` (string): Ihr Event-Typ, `w:` gefolgt vom Namen.

- `deleted` (boolean): Immer `true`.

Gibt `404` zurück, wenn keine Definition passt.

**Anfrage** `DELETE /workspace/events/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```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**

```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**

```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);
```

**200**

```json
{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "deleted": true
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/workspace-events/delete/