Události

Odesílejte události workspace a vlastní události a čtěte proud událostí, ze kterého vycházejí webhooky: doručení, nedoručení, otevření a další.

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

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

Odeslání události

Zaznamená jednu událost workspace (w:<name>), nebo vlastní událost (c:<name>). Funguje s API klíči s oprávněním full i events. Kdy použít kterou, najdete na stránce Sledování událostí. Události jsou součástí tarifů Pro, Business a Custom, s nejvýše 100 typy událostí v tarifu Pro a 1 000 v tarifu Business.

Událost workspace musí být nejdřív definovaná. Její properties se kontrolují podle definice.
Vlastní událost žádnou definici nepotřebuje. Její properties může být libovolný objekt JSON.

Systémové události, například email.delivered, zaznamenává Emailit a odeslat je nelze. Pokud chcete zaznamenat víc událostí jedním voláním, použijte Dávkové odeslání událostí.

POST/events

Parametry v těle požadavku

typestringpovinné

w:<name> pro událost workspace, nebo c:<name> pro vlastní událost, například c:order.completed. Název má od 1 do 100 znaků (písmena, číslice, ., - nebo _) a začíná písmenem nebo číslicí.

propertiesobject

Data události. Výchozí hodnota je {}.

Události workspace: jen vlastnosti z definice, každá se svým typem. Povinné vlastnosti musí být uvedené, null nechá volitelnou vlastnost prázdnou a hodnoty typu datum se ukládají ve formátu ISO 8601 v UTC. Viz Typy vlastností.
Vlastní události: libovolný objekt JSON o velikosti nejvýše 32 KB a s nejvýše 8 úrovněmi zanoření.

emailstring

E-mailová adresa osoby, které se událost týká. Pokud má tuto adresu některý kontakt, událost se přiřadí k němu. Pokud ji nemá žádný, adresa se i tak uloží a událost se zobrazí v aktivitě kontaktu, jakmile ho vytvoříte.

contact_idstring

ID existujícího kontaktu (con_…). Má přednost před email. ID, které neodpovídá žádnému kontaktu ve workspace, vrací 422.

anonymous_idstring

Váš vlastní identifikátor návštěvníka nebo zařízení, nejvýše 128 znaků, pro události, které zatím nemůžete přiřadit konkrétní osobě.

occurred_atstring | integer

Kdy k události došlo: datum a čas ve formátu ISO 8601, nebo časové razítko v milisekundách. Výchozí hodnota je aktuální čas. Může být v minulosti, ale nejvýše 24 hodin v budoucnosti.

contextobject

Kde k události došlo: page (url, path, title, referrer, search), campaign (source, medium, name, term, content), locale a timezone. Neznámé klíče se zahodí a dlouhé hodnoty se zkrátí.

Kontakty se jen dohledávají, nikdy se nevytvářejí. Emailit k událostem neukládá IP adresy.

Odpověď

Vrací 201 Created s událostí: object, id, type, created_at a data. data.object obsahuje, co se uložilo:

objectstring

workspace_event, nebo custom_event.

namestring

Název události bez předpony.

propertiesobject

Zvalidované vlastnosti.

contactobject | null

id a email kontaktu, ke kterému událost patří. id je null, když je známý jen e-mail. null, pokud jste neposlali ani jedno z nich.

anonymous_idstring | null

anonymous_id, které jste poslali.

occurred_atstring

Kdy k události došlo, v UTC.

sourcestring

U tohoto endpointu api. Události ze sledovacího skriptu mají js a testovací události odeslané z webového rozhraní mají dashboard.

contextobject

Uložený kontext. Pokud žádný není, v odpovědi chybí.

API klíč s oprávněním events nemůže číst data, takže dostane událost zpět bez pole data, ve kterém je kontakt dohledaný podle e-mailové adresy.

Stavový kód	Kdy
`400`	Tělo požadavku není objekt JSON.
`403`	API klíč nemá oprávnění `full` ani `events`, nebo tarif nezahrnuje události workspace a vlastní události: v tarifu Pay as you go má `error` hodnotu `plan_required` a `required_plan` hodnotu `pro`. Nic se neuloží.
`422`	Událost je neplatná. Klíči v `errors` jsou pole, například `type` nebo `properties.total`, a `message` opakuje první problém. Vrací se také pro událost `w:`, která není definovaná, pro `contact_id`, které neodpovídá žádnému kontaktu, a pro typ, který workspace dosud neposlal, jakmile vyčerpá počet typů událostí svého tarifu (100 v tarifu Pro, 1 000 v tarifu Business).
`429`	Příliš mnoho požadavků za minutu, nebo workspace dosáhl svého denního limitu férového využití pro události workspace a vlastní události (`code`: `events_daily_limit`). Nic se neuloží. Zkuste to znovu po uplynutí počtu sekund z hlavičky `retry-after`.

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

Dávkové odeslání událostí

Zaznamená až 100 událostí workspace a vlastních událostí jedním požadavkem, například když váš backend pravidelně synchronizuje objednávky. Funguje s API klíči s oprávněním full i events v tarifech Pro, Business a Custom.

Dávka se uloží buď celá, nebo vůbec. Pokud je některá událost neplatná, neuloží se žádná a odpověď vypíše všechny problémy podle pozice události v seznamu.

POST/events/batch

Parametry v těle požadavku

eventsobject[]povinné

Od 1 do 100 událostí. Každá přijímá stejná pole jako Odeslání události: type, properties, email, contact_id, anonymous_id, occurred_at a context.

Odpověď

Vrací 201 Created s uloženými událostmi v data v pořadí, v jakém jste je poslali. Každá položka má object (event), id, type a created_at. Pokud chcete některou načíst i s jejím data, použijte Načtení události.

Stavový kód	Kdy
`400`	`events` chybí, je prázdné nebo má víc než 100 položek.
`403`	API klíč nemá oprávnění `full` ani `events`, nebo tarif nezahrnuje události workspace a vlastní události: v tarifu Pay as you go má `error` hodnotu `plan_required` a `required_plan` hodnotu `pro`. Nic se neuloží.
`422`	Aspoň jedna událost je neplatná. Nic se neuloží. Klíči v `errors` jsou cesty ve tvaru `events.<index>.<field>`, například `events.3.properties.total`, s indexem počítaným od 0, a `message` opakuje první problém. Událost typu, který workspace dosud neposlal, je neplatná, jakmile workspace vyčerpá počet typů událostí svého tarifu (100 v tarifu Pro, 1 000 v tarifu Business).
`429`	Příliš mnoho požadavků za minutu, nebo by dávka posunula workspace přes jeho denní limit férového využití pro události workspace a vlastní události (`code`: `events_daily_limit`). Nic se neuloží. Zkuste to znovu po uplynutí počtu sekund z hlavičky `retry-after`.

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

Výpis událostí

Vrátí události ve vašem workspace od nejnovějších. Každé doručení webhooku vychází z jedné z těchto událostí, takže přes tento endpoint můžete dodatečně načíst události, které váš endpoint zmeškal. Vyžaduje API klíč s oprávněním full.

GET/events

Parametry dotazu

pageinteger

Číslo stránky, od 1. Výchozí hodnota je 1. Stránky hlubší než 2 500 událostí ((page - 1) × limit > 2500) vracejí 422.

limitinteger

Počet událostí na stránce, od 1 do 100. Výchozí hodnota je 100.

typestring

Typ události, nebo seznam typů oddělených čárkami, například email.delivered,email.bounced. Události workspace a vlastní události se zadávají i s předponou, například c:order.completed. Viz Typy událostí.

scopestring

Jen události z těchto rozsahů, zadaných jako seznam oddělený čárkami: system (události, které zaznamenává Emailit, například email.delivered), workspace (události definované ve workspace, w:<name>) a custom (vlastní události, c:<name>). Například scope=workspace,custom. Výchozí hodnota: všechny rozsahy. Neznámý rozsah vrací 400.

include_databoolean

Nastavte na true, pokud chcete u každé události i obsah data. Výchozí hodnota false vrací jen object, id, type a created_at.

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.

Filtry a řazení

Filtry výpisů jsou jedna úroveň parametrů dotazu ve tvaru key.condition=value. Parametry match, order a direction a seznam podmínek pro každý typ najdete na stránce Filtrování.

Klíče filtrů

Klíč	Typ	Podmínky	Poznámky
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: type, created_at

Bez filtru created_at pokrývá výpis jen poslední 2 dny. Pokud chcete jít dál do minulosti, filtr přidejte, například created_at.after=2026-09-01T00:00:00Z. Starší události jsou dostupné tak dlouho, dokud je drží uchovávání dat vašeho tarifu.

Odpověď

Vrací 200 OK s událostmi v poli data a navíc next_page_url a previous_page_url (na začátku a na konci null). URL stránek zachovávají type, scope, limit a include_data.

Pokud je stránka příliš hluboko, vrací 422 s code: "events_offset_too_large". Místo dalšího stránkování zužte časové období nebo typy.

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

Načtení události

Vrátí jednu událost s úplným obsahem data. id je stejná hodnota, kterou webhooky posílají jako event_id, takže můžete dohledat jakoukoli přijatou událost. Vyžaduje API klíč s oprávněním full.

GET/events/:id

Parametry v cestě

idstringPovinné

ID události, například evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a.

Odpověď

Vrací 200 OK s událostí: object (event), id, type, data a created_at. data.object má stejný tvar jako v obsahu webhooku pro daný typ; viz referenci událostí webhooků.

U událostí workspace (w:) a vlastních událostí (c:) obsahuje data.object pole object (workspace_event, nebo custom_event), name, properties, contact, anonymous_id, occurred_at, source, identity_verified u událostí ze sledovacího skriptu, které uvádějí kontakt, a, pokud existuje, context. Viz Odeslání události.

Pokud ID ve vašem workspace neexistuje, vrací 404 s error: "Event not found".

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