Přejít na obsah
Dokumentace

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

Základní URLhttps://api.emailit.com/v2AutentizaceChybyLimity rychlosti

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.

Každý tarif zahrnuje určitý počet segmentů na workspace, sledovaných i nesledovaných. Viz Limity a kvóty.

POST/segments

Parametry v těle požadavku

namestringpovinné
Název segmentu, nejvýše 191 znaků.
descriptionstring | null
Poznámka pro váš tým, nejvýše 1 000 znaků.
audience_idsstring[]
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.
conditionsobject
Pravidla, kterým musí kontakty odpovídat, popsaná v části Podmínky. Pokud parametr vynecháte, zahrnou se všichni ze zdroje.
trackedbooleanvýchozí: false
Ukládat členy segmentu, aby se vstupy a odchody kontaktů staly událostmi pro automatizace a webhooky. Součást tarifů Pro, Business a Custom. Volí se tady a později ho nelze změnit. Viz Sledované segmenty.

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 kontaktu. Hodnoty se porovnávají převedené na malá písmena.
score score Skóre kontaktu.
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 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 naposledy zaznamenal kontakt na vašem webu.
purchased purchase Objednávky, viz Pravidla aktivity.
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 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. 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 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.
POST/segments
Terminal
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
  }'
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"
}

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}

Parametry v cestě

idstringpovinné
ID segmentu (seg_…).

Odpověď

Vrací objekt segmentu.

objectstring
Vždy segment.
idstring
ID segmentu s předponou seg_.
namestring
Název segmentu.
descriptionstring | null
Poznámka pro váš tým.
audience_idsstring[]
Zdrojové seznamy kontaktů. Prázdné pole znamená všechny kontakty ve workspace.
conditionsobject
Pravidla ve tvaru { "match", "groups": [{ "match", "rules": [...] }] }. Viz Vytvoření segmentu.
trackedboolean
Jestli segment ukládá své členy a hlásí vstupy a odchody. Viz Sledované segmenty.
trackingobject | 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_countinteger
Kontakty, které segmentu právě odpovídají.
subscribed_countinteger
Čá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_atstring
Časová razítka v UTC.

Pokud segment neexistuje, vrací 404.

GET/segments/{id}
Terminal
curl https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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"
}

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

Parametry v cestě

idstringpovinné
ID segmentu (seg_…).

Parametry v těle požadavku

namestring
Nový název, nejvýše 191 znaků. Nesmí být prázdný.
descriptionstring | null
Poznámka pro váš tým, nejvýše 1 000 znaků. null nebo prázdný řetězec ji smaže.
audience_idsstring[]
ID zdrojových seznamů kontaktů. [] znamená všechny kontakty ve workspace.
conditionsobject
Pravidla. Viz Vytvoření segmentu.
trackedboolean
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 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.
POST/segments/{id}
Terminal
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" }'
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"
}

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

Parametry dotazu

pageintegervýchozí: 1
Číslo stránky, začíná na 1.
limitintegervýchozí: 10
Počet segmentů na stránce, od 1 do 100.
with_countsbooleanvýchozí: false
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é.
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.contains=customers nebo created_at.after=2026-09-01. Podmínky pro jednotlivé typy najdete na stránce Filtrování.

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

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

Odpověď

dataobject[]
Objekty segmentů na této stránce. contacts_count a subscribed_count jsou uvedené jen s with_counts.
total_recordsinteger
Počet segmentů, které odpovídají dotazu.
usageobject
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.
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/segments
Terminal
curl -G https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d with_counts=true
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
}

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}

Parametry v cestě

idstringpovinné
ID segmentu (seg_…).

Odpověď

objectstring
Vždy segment.
idstring
ID smazaného segmentu.
namestring
Jeho název.
deletedboolean
Vždy true.
removed_from_campaignsinteger
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í.
DELETE/segments/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "deleted": true,
  "removed_from_campaigns": 1
}

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

Parametry v cestě

idstringpovinné
ID segmentu (seg_…).

Parametry dotazu

pageintegervýchozí: 1
Číslo stránky, začíná na 1.
limitintegervýchozí: 25
Počet kontaktů na stránce, od 1 do 100.
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ů

Kontakty segmentu přijímají stejné klíče filtrů a řazení jako Výpis kontaktů; filtry se uplatní navíc k segmentu, například email.ends_with=acme.com.

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íčTypPodmínkyPoznámky
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
first_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
last_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyKřestní jméno a příjmení bez mezer na začátku a na konci.
audiencesstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyPorovnává se s názvem seznamu kontaktů, který je u kontaktu abecedně první.
created_atdateexact, before, after, empty, not_empty
updated_atdateexact, before, after, empty, not_empty
unsubscribedbooleanexact, not_exact
audience_idstringexact, not_exactJen exact a not_exact. Hodnota je ID seznamu kontaktů (aud_...).
custom_fields.*stringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyMísto * zadejte klíč vlastního pole, například custom_fields.company.contains=Acme.

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: email, first_name, last_name, name, audiences, created_at, updated_at, unsubscribed

Odpověď

dataobject[]
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 mají navíc joined_at.
data[].joined_atstring | 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_recordsinteger
Počet kontaktů, které odpovídají segmentu, vyhledávání a filtrům.
subscribed_countinteger
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_urlstring | 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_urlstring | null
Cesta k předchozí stránce, nebo null na první stránce.

Pokud segment neexistuje, vrací 404.

GET/segments/{id}/contacts
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d email.ends_with=acme.com
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
}

Načtení růstu segmentu

Vrací historii sledovaného segmentu: 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

Parametry v cestě

idstringpovinné
ID segmentu (seg_…).

Parametry dotazu

daysintegervýchozí: 30
Počet vrácených dní, od 1 do 365, končí dneškem.

Odpověď

objectstring
Vždy segment_growth.
segment_idstring
ID segmentu.
dataobject[]
Jeden řádek na každý den.
data[].datestring
Den v UTC, YYYY-MM-DD.
data[].members_countinteger | 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_countinteger
Počet kontaktů, které ten den do segmentu vstoupily.
data[].left_countinteger
Počet kontaktů, které ten den segment opustily.
Stavový kód Kdy
404 Segment neexistuje.
422 Segment není sledovaný.
GET/segments/{id}/growth
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d days=7
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 }
  ]
}

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 a náhled se nepočítá do limitu segmentů v tarifu. Vyžaduje API klíč s oprávněním full.

POST/segments/preview

Parametry v těle požadavku

audience_idsstring[]
ID seznamů kontaktů, ze kterých by segment čerpal. Prázdná hodnota nebo vynechání znamená všechny kontakty.
conditionsobject
Pravidla. Viz Vytvoření segmentu.
limitintegervýchozí: 10
Počet kontaktů ve vzorku, od 1 do 25.

Odpověď

objectstring
Vždy segment_preview.
audience_idsstring[]
Zdrojové seznamy kontaktů bez duplicit.
conditionsobject
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_countinteger
Počet kontaktů, které definici odpovídají.
subscribed_countinteger
Kolika z nich mohou kampaně odesílat.
contactsobject[]
Nejnovější odpovídající kontakty ve stejném tvaru jako u endpointu Výpis kontaktů segmentu.

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

POST/segments/preview
Terminal
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
  }'
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"
    }
  ]
}

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

Odpověď

dataobject[]
Jedna položka na každé pole.
data[].keystring
Hodnota, kterou použijete jako field pravidla, například email_domain nebo custom_fields.plan.
data[].labelstring
Zobrazovaný název. U vlastních polí název vlastního pole.
data[].typestring
string, number, date, datetime, boolean, enum, multi, audience, metric, moment, purchase, view, cart, coupon nebo campaign_activity. Viz Vytvoření segmentu. Pole aktivity, například purchased, přijímají jako hodnotu objekt, viz Pravidla aktivity.
data[].groupstring
contact, custom_fields, audiences, commerce (nákupní data) nebo engagement (aktivita v kampaních).
data[].operatorsstring[]
Operátory, které pole přijímá.
data[].valuesobject[]
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í.
GET/segments/fields
Terminal
curl https://api.emailit.com/v2/segments/fields \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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"]
    }
  ]
}

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.