Přeskočit na obsah
API dokumentace

Seznamy a segmenty

SeznamSegment
Členstvívýslovné: kontakty do něj přidáte (ručně, formulářem, importem, automatizací)podle podmínek: kontakt je členem, dokud podmínky splňuje
E-shopjeden e-shop, nebo celá firmavždy jeden e-shop
Typické použitíodběr newsletteru, VIP klub, kontakty z akce„utratili přes 3 000 Kč za rok“, „neotevřeli 90 dní“
Kampaňanoano
Podmínka v automatizacicontact_in_listpravidla segmentu přímo v podmínce

Seznamy

  • GET /lists, POST /lists, PATCH /lists/{id}, DELETE /lists/{id}.
  • Ruční seznamy (manualMembers: true): členy přidáváte a odebíráte sami.
  • Seznamy napojené na e-shop (systemKind shop_contacts, shop_newsletter, shop_unsubscribed) plní synchronizace e-shopu; přidat nebo odebrat člena = 409 conflict / locked.
  • Formulářové seznamy plní formuláře, členy jde přidávat i ručně.
  • publicName je název seznamu, který kontakt uvidí na stránce nastavení odběru.

Stavy členství: confirmed (potvrzený), unconfirmed (čeká na potvrzení odběru), unsubscribed (odhlásil se z tohoto seznamu), removed (odebraný).

Požadavek: POST /api/v1/tenants/{tenant}/lists
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "VIP zákazníci",
  "publicName": "Novinky pro VIP",
  "shopId": null,
  "notifyOnUnsubscribe": false,
  "notifyOnAdd": false,
  "note": ""
}
JSON
Odpověď: 201 Created
{
  "id": "41",
  "name": "VIP zákazníci",
  "publicName": "Novinky pro VIP",
  "shopId": null,
  "systemKind": null,
  "locked": false,
  "manualMembers": true,
  "tags": [],
  "counts": {
    "total": 0,
    "byBucket": {
      "active": 0,
      "unconfirmed": 0,
      "unsubscribed": 0,
      "bounced": 0,
      "complained": 0,
      "blacklisted": 0
    }
  },
  "createdAt": "2026-10-01T08:00:00.000Z",
  "notifyOnUnsubscribe": false,
  "notifyOnAdd": false,
  "note": ""
}

Přidání a odebrání členů

POST /lists/{id}/members s {"contactIds": [...]} (1 až 1 000 ID):

  • už člen = alreadyMember,
  • kontakt odhlášený z tohoto seznamu, odhlášený celkově, nedoručitelný nebo potlačený = skipped (nikdy ho znovu nepřihlásí),
  • ostatní = added (kontakt čekající na potvrzení se přidá jako unconfirmed).
Požadavek: POST /api/v1/tenants/{tenant}/lists/41/members
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists/41/members" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "contactIds": [
    "1202"
  ]
}
JSON
Odpověď: 200 OK
{
  "added": 1,
  "alreadyMember": 0,
  "skipped": 0
}
  • POST /lists/{id}/members/remove člena odebere (stav removed), POST /lists/{id}/members/unsubscribe ho z tohoto seznamu odhlásí.
  • Přidání do seznamu může spustit zapnutou automatizaci se spouštěčem list_added.

Segmenty

Segment patří jednomu e-shopu a vyhodnocuje se nad kontakty s tímto hlavním e-shopem. Definice je strom skupin A (all) / NEBO (any) a pravidel:

Definice segmentu
{"type": "group", "match": "all", "rules": [
  {"type": "list", "operator": "in", "listId": "43"},
  {"type": "group", "match": "any", "rules": [
    {"type": "order_value", "operator": "gte", "amount": "3000", "currency": "CZK", "shopId": "15", "days": "365"},
    {"type": "field", "field": "lastClickAt", "operator": "in_last_days", "value": "30"}]}]}
  • Nejvýš 8 úrovní skupin a 50 pravidel. Prázdná podskupina je chyba; prázdný kořen odpovídá všem kontaktům e-shopu (uložit ale jde jen segment s aspoň jedním pravidlem).
  • Hodnoty pravidel jsou řetězce: počet dní "30" (1 až 3 650), částka "1500.50", datum "2026-09-30".
  • Dny jsou kalendářní dny v časové zóně firmy: „za posledních 30 dní“ = od dneška minus 30 dní včetně dneška; „ne za posledních N dní“ platí i pro prázdné datum (nikdy neotevřel).
  • Objednávky se počítají jen dokončené; order_value sčítá jen jednu měnu (currency je povinná).
  • refresh: daily (vyhodnocuje se živě) nebo static (snímek členů při každém uložení).

Typy pravidel: field (pole kontaktu), list (členství), order_count, order_value, last_order, order_attribute (kód, kategorie nebo značka v objednávce), engagement (A až E, N), purpose (platný souhlas), custom_field, campaign (doručeno, otevřeno, kliknuto), segment (člen jiného segmentu). Všechna pole a operátory: Reference automatizací › Pravidla segmentů.

Živý náhled počtu

POST /segments/preview spočítá kontakty bez uložení: matched (splní podmínky), mailable (z nich těch, kterým lze psát), total (všechny kontakty e-shopu).

Požadavek: POST /api/v1/tenants/{tenant}/segments/preview
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments/preview" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "shopId": "15",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "operator": "in",
        "listId": "43"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "type": "order_value",
            "operator": "gte",
            "amount": "3000",
            "currency": "CZK",
            "shopId": "15",
            "days": "365"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "operator": "in_last_days",
            "value": "30"
          }
        ]
      }
    ]
  }
}
JSON
Odpověď: 200 OK
{
  "matched": 0,
  "mailable": 0,
  "total": 0
}

Uložení

Požadavek: POST /api/v1/tenants/{tenant}/segments
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Aktivní a utrácející",
  "shopId": "15",
  "refresh": "daily",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "operator": "in",
        "listId": "43"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "type": "order_value",
            "operator": "gte",
            "amount": "3000",
            "currency": "CZK",
            "shopId": "15",
            "days": "365"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "operator": "in_last_days",
            "value": "30"
          }
        ]
      }
    ]
  }
}
JSON
Odpověď: 201 Created
{
  "id": "31",
  "name": "Aktivní a utrácející",
  "publicName": "",
  "shopId": "15",
  "refresh": "daily",
  "matched": 0,
  "mailable": 0,
  "computedAt": "2026-10-01T08:00:00.000Z",
  "ruleCount": 3,
  "tags": [],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "listId": "43",
        "operator": "in"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "days": "365",
            "type": "order_value",
            "amount": "3000",
            "shopId": "15",
            "currency": "CZK",
            "operator": "gte"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "value": "30",
            "operator": "in_last_days"
          }
        ]
      }
    ]
  },
  "signatureHtml": ""
}

Chybné pravidlo vrátí 400 s cestou k poli: definition.<indexy od kořene>.<pole>. Tady měna nepatří e-shopu:

Požadavek: POST /api/v1/tenants/{tenant}/segments
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Chybný",
  "shopId": "15",
  "refresh": "daily",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "order_value",
        "operator": "gte",
        "amount": "3000",
        "currency": "EUR",
        "shopId": "15"
      }
    ]
  }
}
JSON
Odpověď: 400 Bad Request
{
  "error": {
    "code": "validation",
    "message": "definition.0.currency"
  }
}
  • Odkazy mezi segmenty (segment) smí vést jen na segment stejného e-shopu, nesmí vytvořit cyklus ani řetězec delší než 5 (definition.segmentCycle, definition.segmentDepth).
  • E-shop uloženého segmentu se nemění (400 shop). Název je ve firmě jedinečný (409 name).