# Segmenty API

> Ukládejte filtry nad kontakty, vypisujte, kdo jim odpovídá, a procházejte vývoj sledovaných segmentů v čase.

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

## Vytvoření segmentu — POST /segments

> Vytvořte segment, tedy uložený filtr nad kontakty ze všech kontaktů nebo z vybraných seznamů kontaktů, a zvolte, jestli bude sledovaný. Alfaverze: otevřená jen týmu Emailitu.

# Vytvoření segmentu

Vytvoří segment: uložený filtr nad kontakty workspace. Vyžaduje API klíč s oprávněním `full`.

Segment obsahuje kontakty ze svého zdroje (odběratele seznamů v `audience_ids`, nebo všechny kontakty, když je prázdné), které odpovídají jeho `conditions`. Členství se vyhodnocuje živě pokaždé, když se segment počítá, vypisuje, zobrazuje v náhledu nebo ho použije odesílaná kampaň. Viz [Segmenty](/cs/docs/segments/).

Každý tarif zahrnuje určitý počet segmentů na workspace, sledovaných i nesledovaných. Viz [Limity a kvóty](/cs/docs/limits/#plan-limits).

`POST /segments`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v těle požadavku

- `name` (string, povinné): Název segmentu, nejvýše 191 znaků.

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

- `audience_ids` (string[]): Zdroj: ID seznamů kontaktů (`aud_…`) v tomto workspace, nejvýše 100. Segment obsahuje jen kontakty přihlášené aspoň k jednomu z nich. Prázdná hodnota nebo vynechání znamená všechny kontakty ve workspace.

- `conditions` (object): Pravidla, kterým musí kontakty odpovídat, popsaná v části [Podmínky](#conditions). Pokud parametr vynecháte, zahrnou se všichni ze zdroje.

- `tracked` (boolean): Ukládat členy segmentu, aby se vstupy a odchody kontaktů staly událostmi pro [automatizace](/cs/docs/automations/triggers/#segment-triggers) a [webhooky](/cs/docs/webhooks/event-types/#segment-events). Součást tarifů Pro, Business a Custom. Volí se tady a později ho nelze změnit. Viz [Sledované segmenty](/cs/docs/segments/tracked/).

## Podmínky

`conditions` obsahuje skupiny pravidel. `match` na nejvyšší úrovni spojuje skupiny a `match` každé skupiny spojuje její pravidla:

```json
{
  "match": "all",
  "groups": [
    { "match": "any", "rules": [{ "field": "email_domain", "operator": "in", "value": ["acme.com", "globex.io"] }] },
    { "match": "all", "rules": [{ "field": "status", "operator": "equals", "value": "subscribed" }] }
  ]
}
```

- `match` je `all` (výchozí), nebo `any`, na nejvyšší úrovni i v každé skupině.
- Pokud chcete zahrnout všechny ze zdroje, vynechte `conditions`, nebo nepošlete žádné skupiny. Prázdné skupiny se zahodí.
- Přijímá se i plochý tvar `{ "match": "any", "rules": [...] }`, který se uloží jako jedna skupina.
- Segment může mít nejvýše 10 skupin a celkem 50 pravidel.

### Pole

| Pole | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | |
| `email_domain` | string | Část adresy za `@`. |
| `first_name`, `last_name` | string | |
| `status` | enum | `subscribed` (kontakt není globálně odhlášený a je přihlášený aspoň k jednomu seznamu kontaktů, takže ho kampaně zasáhnou), nebo `unsubscribed`. Operátory: `equals`, `not_equals`. |
| `created_at`, `updated_at` | datetime | Kdy byl kontakt vytvořen nebo naposledy změněn, porovnává se v UTC. |
| `audience` | audience | Členství s přihlášením. `in` odpovídá kontaktům přihlášeným k některému ze seznamů s danými ID, `not_in` kontaktům, které nejsou přihlášené k žádnému z nich. |
| `tags` | tags | [Štítky](/cs/docs/contacts/tags-and-score/) kontaktu. Hodnoty se porovnávají převedené na malá písmena. |
| `score` | score | [Skóre kontaktu](/cs/docs/contacts/tags-and-score/#lead-score). |
| `custom_fields.<key>` | podle pole | Textová pole jsou `string`, číselná `number`, datová `date` (`YYYY-MM-DD`), logická `boolean`, výběrová `enum` a vícevýběrová `multi`. |
| `orders_count`, `total_spent`, `average_order_value` | metric | Z [objednávek](/cs/docs/commerce/) kontaktu. U kontaktů bez objednávek 0. Částky jsou v měně objednávek kontaktu. |
| `first_order_at`, `last_order_at` | moment | U kontaktů bez objednávek nenastavené. |
| `expected_next_order_at` | moment | Poslední objednávka plus průměrný odstup mezi objednávkami kontaktu. Nastavuje se od druhé objednávky a může být v budoucnosti. |
| `churn_risk` | enum | `low`, `medium` nebo `high`: doba od poslední objednávky porovnaná s obvyklým odstupem kontaktu (nejméně 14 dní), u jednorázových kupujících s 90 dny. Bez objednávek nenastavené. |
| `last_active_at` | moment | Kdy [měřicí skript](/cs/docs/commerce/connect-your-shop/#the-tracking-script) naposledy zaznamenal kontakt na vašem webu. |
| `purchased` | purchase | Objednávky, viz [Pravidla aktivity](#activity-rules). |
| `viewed_product` | view | Zobrazení produktů zaznamenaná měřicím skriptem. |
| `cart` | cart | Otevřené a opuštěné košíky. |
| `used_coupon` | coupon | Objednávky, ve kterých byl použit slevový kód. |
| `campaign_activity` | campaign_activity | Přijaté, otevřené nebo prokliknuté e-maily z kampaní. |

[Výpis polí pro segmenty](/cs/docs/api-reference/segments/fields/) vrací pole vašeho workspace včetně vlastních polí a seznamů kontaktů s operátory, které každé z nich přijímá.

### Operátory

| Typ | Operátory |
| --- | --- |
| string | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `in`, `not_in`, `is_set`, `is_not_set` |
| number | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between`, `is_set`, `is_not_set` |
| date | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago`, `in_next_days`, `is_set`, `is_not_set` |
| datetime | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago` |
| boolean | `is_true`, `is_false`, `is_set`, `is_not_set` |
| enum | `in`, `not_in`, `is_set`, `is_not_set` |
| multi | `in` (má některou z hodnot), `contains_all` (má všechny hodnoty), `not_in` (nemá žádnou z hodnot), `is_set`, `is_not_set` |
| audience | `in`, `not_in` |
| tags | `in` (má některý ze štítků), `contains_all` (má všechny štítky), `not_in` (nemá žádný ze štítků), `is_set` (má nějaký štítek), `is_not_set` (nemá žádné štítky) |
| score | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between` |
| metric | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between` |
| moment | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago`, `in_next_days`, `is_set`, `is_not_set` |
| purchase, view, coupon | `has`, `has_not` |
| cart | `has_open_cart`, `has_abandoned_cart`, `has_no_open_cart` |
| campaign_activity | `received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked`, `received_not_opened`, `received_not_clicked` |

### Hodnoty

- Textová porovnání u polí typu string nerozlišují velikost písmen. Hodnoty výběrových a vícevýběrových polí se musí shodovat přesně.
- `not_equals`, `not_contains` a `not_in` odpovídají i kontaktům, které hodnotu nemají.
- `in`, `not_in` a `contains_all` přijímají seznam nejvýše 100 hodnot. Textové hodnoty mohou mít nejvýše 500 znaků.
- `between` přijímá `[from, to]` včetně obou mezí: dvě čísla, nebo dvě data `YYYY-MM-DD`.
- `on`, `before` a `after` přijímají datum `YYYY-MM-DD`. `before` a `after` daný den nezahrnují.
- `in_last_days`, `more_than_days_ago` a `in_next_days` přijímají celý počet dní od 1 do 3 650, počítaný od okamžiku vyhodnocení segmentu. Datová vlastní pole porovnávají kalendářní dny v UTC; `created_at` a `updated_at` používají přesné časy, takže `in_last_days` s hodnotou `7` znamená posledních 7 × 24 hodin.
- `is_set`, `is_not_set`, `is_true` a `is_false` hodnotu nepřijímají. `is_true` odpovídá hodnotám `true`, `1`, `yes` a `on`; `is_false` hodnotám `false`, `0`, `no` a `off`.
- Uložené pravidlo, které už neplatí, například po změně typu jeho vlastního pole, neodpovídá žádným kontaktům. Pravidla pro smazané vlastní pole dál fungují podle hodnot, které kontakty stále mají, ale nová pravidla musí používat existující pole.

### Pravidla aktivity

`purchased`, `viewed_product`, `cart`, `used_coupon` a `campaign_activity` přijímají jako `value` objekt. Všechny klíče jsou volitelné.

| Pole | Klíče hodnoty |
| --- | --- |
| `purchased` | `days`: jen objednávky z posledních N dní. `product_ids`: objednávky s některým z těchto produktů (ID produktů ve vašem obchodě). `categories`: objednávky s produktem z některé z těchto kategorií. `min_count`: aspoň tolik odpovídajících objednávek (výchozí hodnota 1, nejvýše 1 000). Zrušené objednávky se nepočítají. |
| `viewed_product` | `days`, `product_ids`, `categories` a `min_count` jako výše, počítají se ale zobrazení produktů. |
| `cart` | `days` jen s `has_abandoned_cart`: košíky opuštěné za posledních N dní. `has_open_cart` odpovídá aktivnímu košíku, `has_no_open_cart` kontaktům bez aktivního i opuštěného košíku. |
| `used_coupon` | `days` a `coupon`: klíč jednoho [kuponu](/cs/docs/commerce/coupons/). Bez `coupon` se počítá jakýkoli kód. |
| `campaign_activity` | `campaign_id`: jedna kampaň (`cmp_...`), bez něj jakákoli kampaň. `days`: jen posledních N dní, bez něj celá historie. |

`days` je celé číslo od 1 do 3 650. `has_not` je opakem `has` se stejnou hodnotou.

```json
{
  "match": "all",
  "groups": [
    { "match": "all", "rules": [
      { "field": "purchased", "operator": "has", "value": { "categories": ["Shoes"], "days": 180 } },
      { "field": "churn_risk", "operator": "in", "value": ["medium", "high"] },
      { "field": "campaign_activity", "operator": "clicked", "value": { "days": 90 } }
    ] }
  ]
}
```

`received_not_opened` a `received_not_clicked` odpovídají kontaktům, které dostaly aspoň jeden odpovídající e-mail z kampaně a žádný z nich neotevřely, respektive v žádném neklikly. Otevření jsou přibližná: Apple Mail načítá obrázky každého e-mailu, který přijme.

## Odpověď

Vrací `201 Created` s [objektem segmentu](/cs/docs/api-reference/segments/get/) včetně `contacts_count` a `subscribed_count`. Nový sledovaný segment začíná s `tracking.status` nastaveným na `syncing`, zatímco Emailit zaznamenává jeho aktuální členy.

| Stavový kód | Kdy |
| --- | --- |
| `400` | Chybí `name`, nebo má některé pole špatný typ. |
| `403` | `tracked` je `true` a tarif sledované segmenty nezahrnuje. Tělo odpovědi je `{"error": "plan_required", "required_plan": "pro", ...}`. |
| `422` | Některé pole nebo pravidlo je neplatné: klíči v `errors` jsou jejich cesty, například `conditions.groups.0.rules.1.value`, a `message` opakuje první problém. Vrací se také, když workspace dosáhl limitu segmentů svého tarifu; takové tělo obsahuje `usage.used` a `usage.limit`. |

**Požadavek** `POST /segments`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro customers renewing soon",
    "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
    "conditions": {
      "match": "all",
      "groups": [{
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }]
    },
    "tracked": true
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Pro customers renewing soon',
    audience_ids: ['aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a'],
    conditions: {
      match: 'all',
      groups: [{
        match: 'all',
        rules: [
          { field: 'custom_fields.plan', operator: 'in', value: ['pro', 'enterprise'] },
          { field: 'custom_fields.renews_on', operator: 'in_next_days', value: 30 },
        ],
      }],
    },
    tracked: true,
  }),
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "Pro customers renewing soon",
        "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
        "conditions": {
            "match": "all",
            "groups": [{
                "match": "all",
                "rules": [
                    {"field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"]},
                    {"field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30},
                ],
            }],
        },
        "tracked": True,
    },
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'Pro customers renewing soon',
        'audience_ids' => ['aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a'],
        'conditions' => [
            'match' => 'all',
            'groups' => [[
                'match' => 'all',
                'rules' => [
                    ['field' => 'custom_fields.plan', 'operator' => 'in', 'value' => ['pro', 'enterprise']],
                    ['field' => 'custom_fields.renews_on', 'operator' => 'in_next_days', 'value' => 30],
                ],
            ]],
        ],
        'tracked' => true,
    ],
]);
$segment = json_decode($response->getBody(), true);
```

**201**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": null,
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "syncing",
    "synced_at": null
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-18T12:00:00.000000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}
```

**403**

```json
{
  "error": "plan_required",
  "message": "Tracked segments are included with Pro and Business.",
  "required_plan": "pro"
}
```

**422 Validace**

```json
{
  "message": "Validation failed. conditions.groups.0.rules.1.value: Enter a whole number of days between 1 and 3650.",
  "errors": {
    "conditions.groups.0.rules.1.value": [
      "Enter a whole number of days between 1 and 3650."
    ]
  }
}
```

**422 Limit**

```json
{
  "error": "Pay as you go includes 3 segments.",
  "message": "Pay as you go includes 3 segments.",
  "usage": {
    "used": 3,
    "limit": 3
  }
}
```

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

## Načtení segmentu — GET /segments/{id}

> Načtěte segment s jeho zdrojem, pravidly, stavem sledování a živými počty kontaktů. Alfaverze: otevřená jen týmu Emailitu.

# Načtení segmentu

Načte segment a spočítá jeho kontakty v okamžiku volání. Vyžaduje API klíč s oprávněním `full`.

`GET /segments/{id}`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v cestě

- `id` (string, povinné): ID segmentu (`seg_…`).

## Odpověď

Vrací objekt segmentu.

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

- `id` (string): ID segmentu s předponou `seg_`.

- `name` (string): Název segmentu.

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

- `audience_ids` (string[]): Zdrojové seznamy kontaktů. Prázdné pole znamená všechny kontakty ve workspace.

- `conditions` (object): Pravidla ve tvaru `{ "match", "groups": [{ "match", "rules": [...] }] }`. Viz [Vytvoření segmentu](/cs/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Jestli segment ukládá své členy a hlásí vstupy a odchody. Viz [Sledované segmenty](/cs/docs/segments/tracked/).

- `tracking` (object | null): `null` u segmentů, které nejsou sledované. U sledovaných segmentů: - `status`: `active`, když se členové udržují aktuální, `syncing`, zatímco Emailit po vytvoření segmentu nebo obnovení sledování zaznamenává aktuální členy, nebo `paused`, když tarif workspace už sledované segmenty nezahrnuje. - `synced_at`: kdy se celý segment naposledy porovnal se svými pravidly, nebo `null` před prvním porovnáním.

- `contacts_count` (integer): Kontakty, které segmentu právě odpovídají.

- `subscribed_count` (integer): Část `contacts_count`, které mohou kampaně odesílat: kontakty, které nejsou globálně odhlášené a jsou přihlášené aspoň k jednomu seznamu kontaktů. Blokované adresy se stále započítávají.

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

Pokud segment neexistuje, vrací `404`.

**Požadavek** `GET /segments/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$segment = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-02T09:14:03.551000+00:00"
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

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

## Úprava segmentu — POST /segments/{id}

> Změňte název, popis, zdrojové seznamy kontaktů nebo pravidla segmentu. To, jestli je segment sledovaný, změnit nelze. Alfaverze: otevřená jen týmu Emailitu.

# Úprava segmentu

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

Kampaně vyhodnocují segment při odeslání, takže nová pravidla platí pro každou kampaň, která se ještě neodeslala, včetně naplánovaných.

U [sledovaného segmentu](/cs/docs/segments/tracked/) změna `audience_ids` nebo `conditions` porovná uložené členy s novými pravidly. Kontakty, které kvůli změně vstoupí nebo odejdou, odešlou události `segment.contact_added` a `segment.contact_removed` s `reason` nastaveným na `segment_updated`. Webhooky je dostanou, ale automatizace nespouštějí.

`POST /segments/{id}`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v cestě

- `id` (string, povinné): ID segmentu (`seg_…`).

## Parametry v těle požadavku

- `name` (string): Nový název, nejvýše 191 znaků. Nesmí být prázdný.

- `description` (string | null): Poznámka pro váš tým, nejvýše 1 000 znaků. `null` nebo prázdný řetězec ji smaže.

- `audience_ids` (string[]): ID zdrojových seznamů kontaktů. `[]` znamená všechny kontakty ve workspace.

- `conditions` (object): Pravidla. Viz [Vytvoření segmentu](/cs/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Přijímá se jen se současnou hodnotou segmentu. Sledování se volí při vytvoření segmentu; pokud ho chcete změnit, vytvořte nový segment.

## Odpověď

Vrací upravený [objekt segmentu](/cs/docs/api-reference/segments/get/) s aktuálními počty.

| Stavový kód | Kdy |
| --- | --- |
| `404` | Segment neexistuje. |
| `422` | Některé pole nebo pravidlo je neplatné, nebo se `tracked` liší od současné hodnoty segmentu. Klíči v `errors` jsou cesty k polím. |

**Požadavek** `POST /segments/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro customers renewing this month" }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Pro customers renewing this month' }),
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"name": "Pro customers renewing this month"},
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['name' => 'Pro customers renewing this month'],
]);
$segment = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing this month",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

**422**

```json
{
  "message": "Validation failed. tracked: Tracking is chosen when a segment is created and can't be changed. Create a new segment instead.",
  "errors": {
    "tracked": [
      "Tracking is chosen when a segment is created and can't be changed. Create a new segment instead."
    ]
  }
}
```

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

## Výpis segmentů — GET /segments

> Vypište segmenty ve workspace od nejnovějšího, volitelně s živými počty kontaktů a s využitím segmentů v tarifu. Alfaverze: otevřená jen týmu Emailitu.

# Výpis segmentů

Vrací segmenty workspace od nejnovějšího a kolik segmentů z tarifu je využito. Vyžaduje API klíč s oprávněním `full`.

`GET /segments`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry dotazu

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

- `limit` (integer): Počet segmentů na stránce, od 1 do 100.

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

- `with_counts` (boolean): Přidá ke každému segmentu `contacts_count` a `subscribed_count`. Počítání vyhodnocuje každý segment na stránce, proto je ve výchozím stavu vypnuté.

- `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.contains=customers` nebo `created_at.after=2026-09-01`. Podmínky pro jednotlivé typy najdete na stránce [Filtrování](/cs/docs/api-reference/filtering/).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Klíče řazení pro `order`: `name`, `created_at`, `updated_at`.

## Odpověď

- `data` (object[]): [Objekty segmentů](/cs/docs/api-reference/segments/get/) na této stránce. `contacts_count` a `subscribed_count` jsou uvedené jen s `with_counts`.

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

- `usage` (object): Segmenty workspace v poměru k tarifu: `used` (všechny segmenty, sledované i nesledované), `limit` (počet segmentů, které tarif zahrnuje) a `tracking_allowed` (jestli tarif zahrnuje sledované segmenty). Viz [Limity a kvóty](/cs/docs/limits/#plan-limits).

- `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 /segments`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d with_counts=true
```

**Node.js**

```javascript
const params = new URLSearchParams({ with_counts: 'true' });
const res = await fetch(`https://api.emailit.com/v2/segments?${params}`, {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data: segments, usage } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"with_counts": "true"},
)
segments = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['with_counts' => 'true'],
]);
$segments = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "object": "segment",
      "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
      "name": "Pro customers renewing soon",
      "description": "Pro and Enterprise plans that renew in the next 30 days.",
      "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
      "conditions": {
        "match": "all",
        "groups": [
          {
            "match": "all",
            "rules": [
              { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
              { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
            ]
          }
        ]
      },
      "tracked": true,
      "tracking": {
        "status": "active",
        "synced_at": "2026-10-18T00:30:04.211000+00:00"
      },
      "contacts_count": 412,
      "subscribed_count": 398,
      "created_at": "2026-10-02T09:14:03.551000+00:00",
      "updated_at": "2026-10-02T09:14:03.551000+00:00"
    }
  ],
  "total_records": 1,
  "usage": {
    "used": 1,
    "limit": 10,
    "tracking_allowed": true
  },
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Smazání segmentu — DELETE /segments/{id}

> Smažte segment. Koncepty kampaní, které mu odesílají, o něj přijdou; koncepty, které ho vylučují, nelze odeslat, dokud vyloučení nenahradíte. Smazání blokují naplánované nebo odesílané kampaně a automatizace, které segment používají. Alfaverze: otevřená jen týmu Emailitu.

# Smazání segmentu

Smaže segment. Vyžaduje API klíč s oprávněním `full`.

- Segment nelze smazat, dokud ho používá kampaň, která je naplánovaná, ve frontě, odesílá se nebo se testuje. Nejdřív změňte příjemce kampaně.
- Segment nelze smazat, dokud ho kterákoli nesmazaná automatizace v jakémkoli stavu používá: ve spouštěči **Added to segment** nebo **Removed from segment**, v cíli, kroku **Wait until** nebo podmínce ukončení na tyto události, nebo v pravidle **Segment** v podmínce. Nejdřív tyto automatizace změňte.
- Koncepty kampaní, které segmentu odesílají, ho ztratí ze svých příjemců a `removed_from_campaigns` udává, kolika konceptů se to týká. Koncepty, které segment vylučují, si vyloučení ponechají, takže je nelze odeslat, dokud ho nenahradíte: jeho vypuštění by kampaň poslalo lidem, které jste chtěli vynechat. Odeslané, zrušené a archivované kampaně si odkaz ponechají jako historii.
- U sledovaného segmentu se smažou i jeho uložení členové a historie růstu.

`DELETE /segments/{id}`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v cestě

- `id` (string, povinné): ID segmentu (`seg_…`).

## Odpověď

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

- `id` (string): ID smazaného segmentu.

- `name` (string): Jeho název.

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

- `removed_from_campaigns` (integer): Počet konceptů kampaní, které už segmentu neodesílají.

| Stavový kód | Kdy |
| --- | --- |
| `404` | Segment neexistuje. |
| `409` | Segment používá kampaň, která je naplánovaná, ve frontě, odesílá se nebo se testuje, nebo z něj vychází automatizace. Zpráva je jmenovitě uvádí. |

**Požadavek** `DELETE /segments/{id}`

**cURL**

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

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  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/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    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('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "deleted": true,
  "removed_from_campaigns": 1
}
```

**409 Kampaně**

```json
{
  "error": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first.",
  "message": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first."
}
```

**409 Automatizace**

```json
{
  "error": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first.",
  "message": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first."
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

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

## Výpis kontaktů segmentu — GET /segments/{id}/contacts

> Vypište kontakty, které segmentu právě odpovídají, s vyhledáváním, filtry z výpisu kontaktů a u sledovaných segmentů i s časem, kdy který kontakt vstoupil. Alfaverze: otevřená jen týmu Emailitu.

# Výpis kontaktů segmentu

Vrací kontakty, které segmentu odpovídají v okamžiku volání, od nejnovějších. Vyžaduje API klíč s oprávněním `full`.

`GET /segments/{id}/contacts`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v cestě

- `id` (string, povinné): ID segmentu (`seg_…`).

## Parametry dotazu

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

- `limit` (integer): Počet kontaktů na stránce, od 1 do 100.

- `search` (string): Hledá část e-mailové adresy, křestního jména nebo příjmení bez ohledu na velikost písmen.

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

### Klíče filtrů

Kontakty segmentu přijímají stejné klíče filtrů a řazení jako [Výpis kontaktů](/cs/docs/api-reference/contacts/list/); filtry se uplatní navíc k segmentu, například `email.ends_with=acme.com`.

Klíče filtrů a řazení: viz [Filtrování](https://emailit.com/cs/docs/api-reference/filtering/).

## Odpověď

- `data` (object[]): Kontakty na této stránce, každý s `object`, `id`, `email`, `first_name`, `last_name`, `custom_fields`, `unsubscribed`, `audiences` (`id`, `name`, `subscribed`), `created_at` a `updated_at`. Kontakty [sledovaného segmentu](/cs/docs/segments/tracked/) mají navíc `joined_at`.

- `data[].joined_at` (string | null): Jen u sledovaných segmentů: kdy začal aktuální pobyt kontaktu v segmentu. `null`, dokud sledování kontakt nezaznamená, například hned poté, co kontakt začal segmentu odpovídat, dokud je segment ve stavu `syncing`, nebo dokud je sledování ve stavu `paused`.

- `total_records` (integer): Počet kontaktů, které odpovídají segmentu, vyhledávání a filtrům.

- `subscribed_count` (integer): Kolika z nich mohou kampaně odesílat: kontaktům, které nejsou globálně odhlášené a jsou přihlášené aspoň k jednomu seznamu kontaktů.

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

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

Pokud segment neexistuje, vrací `404`.

**Požadavek** `GET /segments/{id}/contacts`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d email.ends_with=acme.com
```

**Node.js**

```javascript
const params = new URLSearchParams({ 'email.ends_with': 'acme.com' });
const res = await fetch(
  `https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts?${params}`,
  { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const { data: contacts } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"email.ends_with": "acme.com"},
)
contacts = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['email.ends_with' => 'acme.com'],
]);
$contacts = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00",
      "joined_at": "2026-10-03T00:30:02.874000+00:00"
    }
  ],
  "total_records": 1,
  "subscribed_count": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/segments/contacts/

## Načtení růstu segmentu — GET /segments/{id}/growth

> Denní počty členů, vstupy a odchody sledovaného segmentu, jeden řádek na každý den v UTC, nejvýše za 365 dní. Alfaverze: otevřená jen týmu Emailitu.

# Načtení růstu segmentu

Vrací historii [sledovaného segmentu](/cs/docs/segments/tracked/): jeden řádek na každý den v UTC, od nejstaršího, končí dneškem. Z těchto dat vychází graf **Growth** na stránce segmentu. Vyžaduje API klíč s oprávněním `full`.

Historie začíná se zahájením sledování. Kontakty zaznamenané prvním zápisem členů po vytvoření segmentu nebo po obnovení sledování se počítají jako členové, ale ne jako vstupy.

`GET /segments/{id}/growth`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v cestě

- `id` (string, povinné): ID segmentu (`seg_…`).

## Parametry dotazu

- `days` (integer): Počet vrácených dní, od 1 do 365, končí dneškem.

## Odpověď

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

- `segment_id` (string): ID segmentu.

- `data` (object[]): Jeden řádek na každý den.

- `data[].date` (string): Den v UTC, `YYYY-MM-DD`.

- `data[].members_count` (integer | null): Počet členů na konci dne, u dneška poslední zjištěný počet. Dny bez nového počtu přebírají předchozí hodnotu, například během pozastavení sledování. Před zahájením sledování `null`.

- `data[].joined_count` (integer): Počet kontaktů, které ten den do segmentu vstoupily.

- `data[].left_count` (integer): Počet kontaktů, které ten den segment opustily.

| Stavový kód | Kdy |
| --- | --- |
| `404` | Segment neexistuje. |
| `422` | Segment není sledovaný. |

**Požadavek** `GET /segments/{id}/growth`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d days=7
```

**Node.js**

```javascript
const res = await fetch(
  'https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth?days=7',
  { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const { data: days } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"days": 7},
)
days = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['days' => 7],
]);
$days = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "object": "segment_growth",
  "segment_id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "data": [
    { "date": "2026-10-12", "members_count": null, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-13", "members_count": 380, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-14", "members_count": 391, "joined_count": 14, "left_count": 3 },
    { "date": "2026-10-15", "members_count": 391, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-16", "members_count": 402, "joined_count": 12, "left_count": 1 },
    { "date": "2026-10-17", "members_count": 405, "joined_count": 6, "left_count": 3 },
    { "date": "2026-10-18", "members_count": 412, "joined_count": 9, "left_count": 2 }
  ]
}
```

**422**

```json
{
  "error": "Growth is recorded for tracked segments only.",
  "message": "Growth is recorded for tracked segments only."
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/segments/growth/

## Náhled segmentu — POST /segments/preview

> Spočítejte kontakty, které by definice segmentu obsahovala, a zobrazte jejich vzorek, aniž byste segment ukládali. Alfaverze: otevřená jen týmu Emailitu.

# Náhled segmentu

Zkontroluje definici segmentu bez uložení: vrátí, kolik kontaktů jí odpovídá, a jejich vzorek. Definice se validuje stejně jako u endpointu [Vytvoření segmentu](/cs/docs/api-reference/segments/create/) a náhled se nepočítá do limitu segmentů v tarifu. Vyžaduje API klíč s oprávněním `full`.

`POST /segments/preview`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Parametry v těle požadavku

- `audience_ids` (string[]): ID seznamů kontaktů, ze kterých by segment čerpal. Prázdná hodnota nebo vynechání znamená všechny kontakty.

- `conditions` (object): Pravidla. Viz [Vytvoření segmentu](/cs/docs/api-reference/segments/create/#conditions).

- `limit` (integer): Počet kontaktů ve vzorku, od 1 do 25.

## Odpověď

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

- `audience_ids` (string[]): Zdrojové seznamy kontaktů bez duplicit.

- `conditions` (object): Pravidla v podobě, v jaké by se uložila: plochý tvar `{ match, rules }` se změní na jednu skupinu a prázdné skupiny se zahodí.

- `contacts_count` (integer): Počet kontaktů, které definici odpovídají.

- `subscribed_count` (integer): Kolika z nich mohou kampaně odesílat.

- `contacts` (object[]): Nejnovější odpovídající kontakty ve stejném tvaru jako u endpointu [Výpis kontaktů segmentu](/cs/docs/api-reference/segments/contacts/).

Pokud je definice neplatná, vrací `422` s `errors`, jehož klíči jsou cesty k polím.

**Požadavek** `POST /segments/preview`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments/preview \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": { "rules": [{ "field": "email_domain", "operator": "equals", "value": "acme.com" }] },
    "limit": 5
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conditions: { rules: [{ field: 'email_domain', operator: 'equals', value: 'acme.com' }] },
    limit: 5,
  }),
});
const preview = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments/preview",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "conditions": {"rules": [{"field": "email_domain", "operator": "equals", "value": "acme.com"}]},
        "limit": 5,
    },
)
preview = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments/preview', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'conditions' => ['rules' => [['field' => 'email_domain', 'operator' => 'equals', 'value' => 'acme.com']]],
        'limit' => 5,
    ],
]);
$preview = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment_preview",
  "audience_ids": [],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "email_domain", "operator": "equals", "value": "acme.com" }
        ]
      }
    ]
  },
  "contacts_count": 8,
  "subscribed_count": 8,
  "contacts": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00"
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. conditions.groups.0.rules.0.operator: \"greater_than\" does not apply to Email domain.",
  "errors": {
    "conditions.groups.0.rules.0.operator": [
      "\"greater_than\" does not apply to Email domain."
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/segments/preview/

## Výpis polí pro segmenty — GET /segments/fields

> Vypište pole kontaktů, vlastní pole a seznamy kontaktů, které mohou používat pravidla segmentů, s operátory a hodnotami, které každé z nich přijímá. Alfaverze: otevřená jen týmu Emailitu.

# Výpis polí pro segmenty

Vrací pole, která mohou pravidla segmentů v tomto workspace používat: pole kontaktu, každé vlastní pole (s typem podle typu vlastního pole), členství v seznamech kontaktů, nákupní data a zapojení do kampaní. Vyžaduje API klíč s oprávněním `full`.

`GET /segments/fields`

> **Segmenty jsou v alfaverzi:** Dokud segmenty testujeme, jsou otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "segments_alpha"`. Viz [Kdo může segmenty používat](/cs/docs/segments/#who-can-use-segments).

## Odpověď

- `data` (object[]): Jedna položka na každé pole.

- `data[].key` (string): Hodnota, kterou použijete jako `field` pravidla, například `email_domain` nebo `custom_fields.plan`.

- `data[].label` (string): Zobrazovaný název. U vlastních polí název vlastního pole.

- `data[].type` (string): `string`, `number`, `date`, `datetime`, `boolean`, `enum`, `multi`, `audience`, `metric`, `moment`, `purchase`, `view`, `cart`, `coupon` nebo `campaign_activity`. Viz [Vytvoření segmentu](/cs/docs/api-reference/segments/create/#fields). Pole aktivity, například `purchased`, přijímají jako hodnotu objekt, viz [Pravidla aktivity](/cs/docs/api-reference/segments/create/#activity-rules).

- `data[].group` (string): `contact`, `custom_fields`, `audiences`, `commerce` (nákupní data) nebo `engagement` (aktivita v kampaních).

- `data[].operators` (string[]): Operátory, které pole přijímá.

- `data[].values` (object[]): Povolené hodnoty jako `value` a `label`: možnosti výběrových a vícevýběrových vlastních polí, `subscribed` a `unsubscribed` pro `status` a seznamy kontaktů workspace pro `audience`. U ostatních polí chybí.

**Požadavek** `GET /segments/fields`

**cURL**

```bash
curl https://api.emailit.com/v2/segments/fields \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/fields', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data: fields } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/fields",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
fields = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/fields', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$fields = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "key": "email",
      "label": "Email",
      "type": "string",
      "group": "contact",
      "operators": ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_set", "is_not_set"]
    },
    {
      "key": "status",
      "label": "Subscription status",
      "type": "enum",
      "group": "contact",
      "operators": ["equals", "not_equals"],
      "values": [
        { "value": "subscribed", "label": "Subscribed" },
        { "value": "unsubscribed", "label": "Unsubscribed" }
      ]
    },
    {
      "key": "audience",
      "label": "Audience",
      "type": "audience",
      "group": "audiences",
      "operators": ["in", "not_in"],
      "values": [
        { "value": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a", "label": "Customers" }
      ]
    },
    {
      "key": "purchased",
      "label": "Purchased",
      "type": "purchase",
      "group": "commerce",
      "operators": [
        "has",
        "has_not"
      ]
    },
    {
      "key": "custom_fields.renews_on",
      "label": "Renews on",
      "type": "date",
      "group": "custom_fields",
      "operators": ["on", "before", "after", "between", "in_last_days", "more_than_days_ago", "in_next_days", "is_set", "is_not_set"]
    }
  ]
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/segments/fields/