Události workspace

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

Základní URLhttps://api.emailit.com/v2Autentizace Chyby Limity rychlosti

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

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.

POST/workspace/events

Parametry v těle požadavku

namestringpovinné

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ý.

titlestring | null

Čitelný název zobrazený ve webovém rozhraní, nejvýše 120 znaků.

descriptionstring | null

Poznámka pro váš tým, nejvýše 1 000 znaků.

propertiesobject[]

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.

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:`.

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

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ě

idstringpovinné

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.

objectstring

Vždy workspace_event.

idstring

ID definice s předponou etp_.

namestring

Název události bez předpony.

typestring

Typ, který posíláte a podle kterého filtrujete: w: a za ním název.

titlestring | null

Čitelný název, který webové rozhraní zobrazuje místo typu, například v aktivitě kontaktu.

descriptionstring | null

Poznámka pro váš tým.

propertiesobject[]

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í.
title, description: volitelné popisky, nebo null.
required: jestli ji musí obsahovat každá událost.

created_at, updated_atstring

Časová razítka v UTC.

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

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

Ú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ě

idstringpovinné

ID definice (etp_…), její název nebo její typ události (w:…).

Parametry v těle požadavku

namestring

Nový název se stejnými pravidly jako při vytvoření.

titlestring | null

Nejvýše 120 znaků. null nebo prázdný řetězec hodnotu vymaže.

descriptionstring | null

Nejvýše 1 000 znaků. null nebo prázdný řetězec hodnotu vymaže.

propertiesobject[]

Nový seznam vlastností, nejvýše 50, stejně jako při vytvoření. [] odebere všechny vlastnosti.

Odpověď

Vrací upravený objekt události workspace.

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.

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

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

pageintegervýchozí: 1

Číslo stránky, začíná na 1.

limitintegervýchozí: 100

Počet definic na stránce, od 1 do 250.

searchstring

Hledá část názvu nebo zobrazovaného názvu bez ohledu na velikost písmen.

matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

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í.

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ěď

dataobject[]

Objekty událostí workspace na této stránce.

total_recordsinteger

Počet definic, které odpovídají dotazu.

next_page_urlstring | 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_urlstring | null

Cesta k předchozí stránce, nebo null na první stránce.

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
}

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ě

idstringpovinné

ID definice (etp_…), její název nebo její typ události (w:…).

Odpověď

objectstring

Vždy workspace_event.

idstring

ID smazané definice.

namestring

Její název.

typestring

Její typ události, w: a za ním název.

deletedboolean

Vždy true.

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

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
}