# Události workspace API

> Definujte události workspace a typy jejich vlastností, aby se události w:, které posíláte, kontrolovaly.

Základní URL: `https://api.emailit.com/v2`. Autentizujte se hlavičkou `Authorization: Bearer <API key>`.

## Vytvoření události workspace — POST /workspace/events

> Definujte událost workspace a typy jejích vlastností. Události tohoto typu se pak posílají s předponou w: a kontrolují se podle definice.

# Vytvoření události workspace

Definuje událost workspace: název a vlastnosti, které nese každá událost tohoto typu, a typ každé vlastnosti. Událost pak posíláte jako `w:<name>` a Emailit odmítne události, které definici neodpovídají. Vyžaduje API klíč s oprávněním `full`.

Události workspace jsou součástí tarifů Pro, Business a Custom. Workspace jich může definovat tolik, kolik typů událostí zahrnuje jeho tarif: 100 v tarifu Pro a 1 000 v tarifu Business, v tarifu Custom bez limitu. Vlastní události (`c:<name>`) definici nepotřebují. Viz [Události workspace](/cs/docs/events/workspace-events/).

`POST /workspace/events`

## Parametry v těle požadavku

- `name` (string, povinné): Název události, například `customer.type`: od 1 do 100 znaků (písmena, číslice, `.`, `-` nebo `_`), začíná písmenem nebo číslicí. Můžete ho poslat i s předponou (`w:customer.type`); předpona se odstraní. Musí být ve workspace jedinečný.

- `title` (string | null): Čitelný název zobrazený ve webovém rozhraní, nejvýše 120 znaků.

- `description` (string | null): Poznámka pro váš tým, nejvýše 1 000 znaků.

- `properties` (object[]): Nejvýše 50 definic vlastností. Výchozí hodnota je `[]`, což znamená, že události tohoto typu nenesou žádné vlastnosti. Každá definice má: - `name` (povinné): od 1 do 64 znaků (písmena, číslice, `-` nebo `_`), začíná písmenem nebo číslicí. Tečky nejsou povolené, protože filtry webhooků a šablony používají tečky k přístupu k vnořeným hodnotám. Názvy musí být v rámci definice jedinečné. - `type` (povinné): `string`, `number`, `date` nebo `boolean`, na velikosti písmen nezáleží. - `title`: popisek, nejvýše 120 znaků. - `description`: nejvýše 1 000 znaků. - `required`: `true`, pokud ji musí obsahovat každá událost. Výchozí hodnota je `false`.

## Odpověď

Vrací `201 Created` s [objektem události workspace](/cs/docs/api-reference/workspace-events/get/).

| Stavový kód | Kdy |
| --- | --- |
| `403` | API klíč nemá oprávnění `full`, nebo je workspace v tarifu Pay as you go: `error` má hodnotu `plan_required` a `required_plan` hodnotu `pro`. |
| `409` | Událost workspace s tímto názvem už existuje. Uvádí to `errors.name`. |
| `422` | Některé pole je neplatné: klíči v `errors` jsou cesty polí, například `name` nebo `properties.1.type`, a `message` opakuje první problém. Vrací se také s `code: "workspace_events_limit"`, když workspace už má tolik událostí workspace, kolik jeho tarif povoluje, a pro název, který začíná na `c:`. |

**Požadavek** `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"]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/workspace-events/create/

## Načtení události workspace — GET /workspace/events/{id}

> Načtěte definici události workspace podle ID nebo názvu i s typy jejích vlastností.

# Načtení události workspace

Načte definici události workspace: její název, zobrazovaný název a vlastnosti, kterých se odesílatelé musí držet. Vyžaduje API klíč s oprávněním `full`.

`GET /workspace/events/{id}`

## Parametry v cestě

- `id` (string, povinné): ID definice (`etp_…`), její název (`customer.type`) nebo její typ události (`w:customer.type`). Pokud to váš klient neudělá sám, zakódujte `:` do URL.

## Odpověď

Vrací objekt události workspace.

- `object` (string): Vždy `workspace_event`.

- `id` (string): ID definice s předponou `etp_`.

- `name` (string): Název události bez předpony.

- `type` (string): Typ, který posíláte a podle kterého filtrujete: `w:` a za ním název.

- `title` (string | null): Čitelný název, který webové rozhraní zobrazuje místo typu, například v aktivitě kontaktu.

- `description` (string | null): Poznámka pro váš tým.

- `properties` (object[]): Vlastnosti, které událost tohoto typu může nést, každá s těmito poli: - `name`: klíč v `properties` události. - `type`: `string`, `number`, `date` nebo `boolean`. Viz [Typy vlastností](/cs/docs/events/workspace-events/#property-types). - `title`, `description`: volitelné popisky, nebo `null`. - `required`: jestli ji musí obsahovat každá událost.

- `created_at, updated_at` (string): Časová razítka v UTC.

Pokud žádná definice neodpovídá, vrací `404` s `error: "Workspace event not found"`.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/workspace-events/get/

## Úprava události workspace — POST /workspace/events/{id}

> Přejmenujte událost workspace, nebo změňte její zobrazovaný název, popis či vlastnosti. Už uložené události se nemění.

# Úprava události workspace

Upraví pole, která předáte, a ostatní ponechá beze změny. Vyžaduje API klíč s oprávněním `full`.

Definice kontroluje jen nové události. Už uložené události si ponechají svůj typ i vlastnosti, takže po změně mohou starší události mít vlastnosti, které definice už neuvádí.

- `properties` nahradí celý seznam. Pokud chcete vlastnost přidat, pošlete aktuální seznam a k němu novou vlastnost.
- Přejmenováním se změní typ, který posíláte. Události uložené pod starým názvem si ho ponechají a nové události se starým názvem se odmítnou, pokud ho znovu nedefinujete.

`POST /workspace/events/{id}`

## Parametry v cestě

- `id` (string, povinné): ID definice (`etp_…`), její název nebo její typ události (`w:…`).

## Parametry v těle požadavku

- `name` (string): Nový název se stejnými pravidly jako při [vytvoření](/cs/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): Nejvýše 120 znaků. `null` nebo prázdný řetězec hodnotu vymaže.

- `description` (string | null): Nejvýše 1 000 znaků. `null` nebo prázdný řetězec hodnotu vymaže.

- `properties` (object[]): Nový seznam vlastností, nejvýše 50, stejně jako při [vytvoření](/cs/docs/api-reference/workspace-events/create/#body-parameters). `[]` odebere všechny vlastnosti.

## Odpověď

Vrací upravený [objekt události workspace](/cs/docs/api-reference/workspace-events/get/).

| Stavový kód | Kdy |
| --- | --- |
| `404` | Žádná definice neodpovídá `id`. |
| `409` | Nový název už má jiná událost workspace. |
| `422` | Některé pole je neplatné: klíči v `errors` jsou cesty polí a `message` opakuje první problém. |

**Požadavek** `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"]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/workspace-events/update/

## Výpis událostí workspace — GET /workspace/events

> Vypište definice událostí workspace seřazené podle názvu, i s typy jejich vlastností, s vyhledáváním a filtry.

# Výpis událostí workspace

Vrací definice událostí workspace seřazené podle názvu. Vyžaduje API klíč s oprávněním `full`.

`GET /workspace/events`

## Parametry dotazu

- `page` (integer): Číslo stránky, začíná na 1.

- `limit` (integer): Počet definic na stránce, od 1 do 250.

- `search` (string): Hledá část názvu nebo zobrazovaného názvu bez ohledu na velikost písmen.

- `match`, `order`, `direction`: viz [Filtrování](https://emailit.com/cs/docs/api-reference/filtering/).

### Klíče filtrů

Filtry se zadávají parametry dotazu ve tvaru `key.condition=value`, například `name.starts_with=order.` nebo `created_at.after=2026-10-01`. Podmínky pro jednotlivé typy najdete na stránce [Filtrování](/cs/docs/api-reference/filtering/).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | Název bez předpony `w:`. |
| `title` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Klíče řazení pro `order`: `name`, `title`, `created_at`, `updated_at`. Ve výchozím stavu se řadí podle `name` vzestupně.

## Odpověď

- `data` (object[]): [Objekty událostí workspace](/cs/docs/api-reference/workspace-events/get/) na této stránce.

- `total_records` (integer): Počet definic, které odpovídají dotazu.

- `next_page_url` (string | null): Cesta k další stránce, nebo `null` na poslední stránce. Obsahuje jen `page` a `limit`; když na ni přejdete, přidejte znovu vyhledávání a filtry.

- `previous_page_url` (string | null): Cesta k předchozí stránce, nebo `null` na první stránce.

**Požadavek** `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
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/workspace-events/list/

## Smazání události workspace — DELETE /workspace/events/{id}

> Smažte definici události workspace. Uložené události zůstanou a nové události tohoto typu se odmítnou.

# Smazání události workspace

Smaže definici události workspace. Vyžaduje API klíč s oprávněním `full`.

Události tohoto typu, které už jsou uložené, zůstanou v logu událostí i u kontaktů. Nové události tohoto typu se odmítají s `422`, dokud ho znovu nedefinujete. Webhooky, které typ odebírají, si odběr ponechají.

`DELETE /workspace/events/{id}`

## Parametry v cestě

- `id` (string, povinné): ID definice (`etp_…`), její název nebo její typ události (`w:…`).

## Odpověď

- `object` (string): Vždy `workspace_event`.

- `id` (string): ID smazané definice.

- `name` (string): Její název.

- `type` (string): Její typ události, `w:` a za ním název.

- `deleted` (boolean): Vždy `true`.

Pokud žádná definice neodpovídá, vrací `404`.

**Požadavek** `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
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/workspace-events/delete/