{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Poštárna API","version":"1.0.0","description":"Poštárna is a multi-tenant e-mail marketing platform with statistics for companies and e-shops (Czech and Slovak). This document describes every\nroute an integration can call. Guides in Czech and Slovak: https://www.postarna.cz/docs/api (index for AI agents:\nhttps://www.postarna.cz/llms.txt, everything in one Markdown file: https://www.postarna.cz/llms-full.txt).\n\n## Three APIs\n* **API v1** (`/api/v1/tenants/{tenant}/...`): the full API, the same one the Poštárna web app uses. JSON in UTF-8.\n* **SmartEmailing compatible API v3** (`/api/v3/...`) and its CSV statistics (`/api/csv/...`): the same paths,\n  envelopes and errors as SmartEmailing's REST API v3, so an existing SE integration only changes the address, the\n  user name and the key. Read operations plus account webhooks.\n* **MCP server** (`POST /mcp`): Model Context Protocol for AI assistants (ChatGPT, Claude, Cursor ...), OAuth 2.1 or an\n  API key.\n\n## Authentication\nCreate an API key in the app: Nastavení › Datové zdroje › API klíče (Settings › Data sources › API keys). The key\n(`pst_` + 43 characters) is shown once. Send it as `Authorization: Bearer pst_...`, or as HTTP Basic with the e-mail\nof an active member of the company as the user name and the key as the password (both work on v1 and v3). A key\nworks only in its own company (tenant), with the roles it was given (never more than its creator has), and with\nscope `full` (read and write) or `read` (only routes whose permission level is read). Keys never reach the members,\ninvitations, API keys and connected apps (those need a signed-in person: 403 `forbidden` / `api_key`).\n\n`{tenant}` in v1 paths is the company's public id (a UUID). Find it with `GET /api/v3/account-info` (`data.guid`) or\nin the app on the API keys page.\n\n## Conventions (API v1)\n* IDs are strings. Times are ISO 8601 in UTC with milliseconds (`2026-09-30T08:00:00.000Z`); local calendar days of\n  the company are `YYYY-MM-DD`; automation settings use local `YYYY-MM-DDTHH:MM` and `HH:MM`.\n* Money is a decimal string next to its `currency` (`\"1290.00\"`, `\"CZK\"`). CZK and EUR are never added up or\n  converted: every sum is per currency.\n* Lists are paged: `page` from 1, `pageSize` 1 to 100 (default 25); the answer is `{items, total, page, pageSize}`.\n  Some grids take `sort` (`name,-createdAt`, at most 3 fields, `-` = descending).\n* Request bodies of POST, PUT and PATCH are `application/json` (415 `validation` / `contentType` otherwise); CSV\n  import and file upload also take `multipart/form-data`. Unknown body fields are ignored.\n* Errors: `{\"error\": {\"code\": \"...\", \"message\": \"<field or detail>\", \"params\": {...}}}`. `code` is stable and\n  machine readable, `message` names the field or the reason, `params` carries details (for example the issues of an\n  automation graph). The API never sends texts for people.\n* No idempotency keys: retry only requests that are safe to repeat (GET, PUT of a whole object, DELETE). For POST,\n  read the state first (for example list the contacts by e-mail) before you retry after a timeout. Concurrent\n  edits of content and automation graphs are guarded by versions (`baseVersion`, 409 `conflict` / `version`).\n\n## Limits\nPer company (all keys together): a bucket of 2 500 requests refilled with 4 requests a second, and 100 000 requests a\nday (refilled continuously). Every answer to a key carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and\n`X-RateLimit-Reset` (unix time when the bucket is full again) of the bucket nearest to running out. Over the limit:\n429 `rate_limited` with `Retry-After` (seconds). Some actions have their own limits (test e-mails 10 per day per\ncampaign or template, contact events 60 per contact in 10 minutes, MCP 300 messages a minute).\n\n## Consent and sending\nPoštárna never e-mails a contact who unsubscribed, bounced, complained or is suppressed, and campaigns only reach\ncontacts with a valid marketing consent. Sending to real recipients (approving a campaign, activating an automation)\nis irreversible: check the audience first (`POST .../campaigns/audience`, `POST .../automations/{id}/test`). Test\ne-mails go only to the company's test addresses (`GET .../test-recipients`).\n","contact":{"name":"deriverge s.r.o.","url":"https://www.postarna.cz/docs/api"},"x-guides":{"cs":"https://www.postarna.cz/docs/api","sk":"https://www.postarna.sk/docs/api","llms":"https://www.postarna.cz/llms.txt","llmsFull":"https://www.postarna.cz/llms-full.txt"}},"servers":[{"url":"https://www.postarna.cz","description":"Production (the same API answers on www.postarna.sk)"}],"security":[{"bearerAuth":[]},{"basicAuth":[]}],"tags":[{"name":"Segments","x-displayName":"Segments","description":"Rule based groups of contacts of one e-shop: an AND / OR tree of conditions, evaluated live (daily) or as a snapshot (static)."}],"x-error-codes":{"conflict":{"meaning":"The change would break the state of the object. `message`: `name` (name taken), `locked` (a list bound to an e-shop), `status` (wrong state, e.g. editing a sent campaign), `recipients` (the audience changed more than 5 % since you counted it, `params.expected` and `params.actual`), `version` (stale `baseVersion`, `params.current`), `confirm` (saving a running automation needs `confirmRunning: true`), `waiting` (contacts wait in a node you remove, `params.nodes`), `runs` (deleting an automation that ran), `trigger` (no manual trigger), `limit` (too many objects).","fix":"Read the object again, then repeat with current data; for `recipients` count the audience again and send the new `expectedRecipients`."},"count_mismatch":{"meaning":"`expectedRecipients` does not match the audience.","fix":"Count again with `POST /campaigns/audience` and send the new number."},"csrf":{"meaning":"Browser session request without the CSRF header (never with an API key).","fix":"Send the API key in `Authorization` instead of cookies."},"empty_segment":{"meaning":"The campaign audience has no recipient.","fix":"Change the audience."},"expired":{"meaning":"The object is no longer available (an export file older than its retention).","fix":"Create it again (POST /exports)."},"forbidden":{"meaning":"The credentials are valid but not allowed here. `message`: `tenant` (another company in the path), `scope` (a read-only key on a write route), `api_key` (members, invitations and keys need a signed-in person), a module name (`contacts`, `campaigns`, `content`, `settings`, `billing`: the key's roles lack the level), `read_only` (support view).","fix":"Use the tenant id of the key (`GET /api/v3/account-info`), a key with scope `full`, or a key whose roles include the module (for example marketing_manager)."},"method_not_allowed":{"meaning":"The path exists but not with this HTTP method.","fix":"Check the method in this document."},"not_found":{"meaning":"The object does not exist in this company (objects of other companies answer the same).","fix":"Check the id; list the objects first."},"not_implemented":{"meaning":"The feature is not available yet.","fix":"Do not rely on it."},"rate_limited":{"meaning":"Too many requests: the company's API limit, or the limit of one action (test e-mails, contact events, sign-in attempts). `Retry-After` says after how many seconds to retry.","fix":"Wait `Retry-After` seconds; spread requests (4 a second sustained)."},"recently_sent":{"meaning":"HTTP 423: the contact cannot be deleted yet, a campaign e-mail to it is queued or went out in the last 24 hours (SmartEmailing answers the same).","fix":"Delete it after 24 hours. A request to be forgotten (GDPR) uses POST /contacts/{id}/erase, which is never refused."},"server":{"meaning":"Unexpected server error.","fix":"Retry later; the request may be repeated if it is safe to repeat."},"suppression_locked":{"meaning":"The address is suppressed for another reason (bounce, complaint, unsubscribe), so the blacklist cannot be added or removed; `params.reason` names it.","fix":"Leave it: such suppressions protect the sender and are removed only one by one (DELETE /suppressions/{email}) when the reason is gone."},"unauthorized":{"meaning":"No valid credentials: the API key is unknown, revoked, expired, idle for 180 days, its creator left the company, or the HTTP Basic user name is not an active member.","fix":"Check the key and the header (`Authorization: Bearer pst_...`). Create a new key in Nastavení › Datové zdroje › API klíče."},"unavailable":{"meaning":"A service the action needs is not available (`mail`: the mail backend refused a test e-mail, `data_key`: encryption key for webhook passwords missing).","fix":"Retry later; tell support when it persists."},"upstream":{"meaning":"An outside service failed (downloading a file by URL, the stock photo service); `params.reason` says why.","fix":"Check the URL or retry later."},"validation":{"meaning":"A parameter or body field is missing, has the wrong type or an invalid value. `message` names it (`email`, `definition.1.0.listId`, `graph` ...), `params` may carry details such as `params.issues` of an automation graph or `params.reason`.","fix":"Fix the named field. For 415 `contentType` send `Content-Type: application/json`; for `body` send a JSON object."}},"paths":{"/api/v1/tenants/{tenant}/segments":{"get":{"operationId":"segments_index","summary":"List segments","tags":["Segments"],"description":"Segments with matched and mailable counts.\n\nFiltry of the grid (routes_grid.py): ?tag= (repeatable), ?idFrom=&idTo=, ?createdFrom=&createdTo=, ?updatedFrom=&updatedTo= (calendar days), ?refresh=static|daily.\n\nContract notes (cs):\n\nParametry `q` (název), `shop`, `page`, `pageSize`; nejnovější první. Položka `SegmentSummary`: `{ \"id\", \"name\", \"publicName\", \"shopId\", \"refresh\", \"matched\", \"mailable\", \"computedAt\", \"ruleCount\", \"createdAt\", \"updatedAt\" }`.\n• `refresh`: `static` = snímek členů při uložení, `daily` = přepočet každých 24 hodin.\n• `matched` = kontakty e-shopu, které splní podmínky (v jakémkoli stavu). `mailable` = z nich přihlášené, bez potlačení a bez slabého souhlasu (výchozí podle D6), tedy kolik jich může dostat kampaň.\n• `computedAt` = čas posledního přepočtu (u statického segmentu čas uložení). Mock počítá denní segment živě.\n• `publicName`: pokročilé nastavení (se-spec 01 §3): název seznamu na odhlašovací stránce, když se segment použije jako rozesílatelný seznam; výchozí `\"\"` (bez vlastního jména).","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Search text."},{"name":"refresh","in":"query","required":false,"schema":{"type":"string"}},{"name":"shop","in":"query","required":false,"schema":{"type":"string"},"description":"Shop id filter."},{"$ref":"#/components/parameters/sort"},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Label filter; repeat for more labels."}],"x-postarna-permission":{"module":"contacts","level":"read","keyScope":"read or full"},"x-mcp-tool":"list_segments","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentSummary"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}}}},"400":{"description":"`validation` (message: q, refresh, sort, tag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"segments_create","summary":"Create a segment","tags":["Segments"],"description":"Creates a segment of one shop from a condition tree {type: group, match: all|any, rules: [...]} (rule types: get_api_reference Segmenty).\n\nContract notes (cs):\n\nTělo `{ \"name\", \"publicName\"?, \"shopId\", \"refresh\"?, \"definition\", \"signatureHtml\"? }` (PATCH podmnožina; bez `refresh` je nový segment `static`, jako v SE „Automaticky obnovovat segment“ výchozí vypnuto). Chyby: 400 `name` (1 až 100 znaků), `publicName` (do 100 znaků), `signatureHtml` (do 5 000 znaků), `shop`, `refresh`, `definition…`; 409 `name` při obsazeném názvu. E-shop uloženého segmentu se nemění (400 `shop`), protože na něm stojí kampaně. Každé uložení statického segmentu udělá nový snímek.","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentInput"},"examples":{"segments-create":{"summary":"docs/api-examples/segments.json create","value":{"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"}]}]}}}}}}},"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"x-mcp-tool":"create_segment","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentDetail"},"examples":{"segments-create":{"summary":"docs/api-examples/segments.json create","value":{"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":""}}}}}},"400":{"description":"`validation` (message: definition, refresh, signatureHtml, tags)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"segments-invalid":{"summary":"docs/api-examples/segments.json invalid","value":{"error":{"code":"validation","message":"definition.0.currency"}}}}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict` (message: name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/preview":{"post":{"operationId":"segments_preview","summary":"Count the contacts of a segment definition (no save)","tags":["Segments"],"description":"Counts a condition tree without saving: matched, mailable and total contacts of the shop.\n\nLive count for the editor: {matched, mailable, total}; the root may be empty (all contacts of the shop).\n\nContract notes (cs):\n\nTělo `{ \"shopId\", \"definition\" }` (smí mít prázdný kořen). Odpověď `{ \"matched\", \"mailable\", \"total\" }`, `total` = všechny kontakty e-shopu. Editor ji volá po každé změně (s krátkou prodlevou) pro živý počet.","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopId":{"type":"string"},"definition":{"$ref":"#/components/schemas/SegmentGroup"}},"required":["shopId","definition"]},"examples":{"segments-preview":{"summary":"docs/api-examples/segments.json preview","value":{"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"}]}]}}}}}}},"x-postarna-permission":{"module":"contacts","level":"read","keyScope":"read or full"},"x-mcp-tool":"preview_segment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentPreview"},"examples":{"segments-preview":{"summary":"docs/api-examples/segments.json preview","value":{"matched":0,"mailable":0,"total":0}}}}}},"400":{"description":"`validation` (message: definition)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/tags":{"post":{"operationId":"segments_tags","summary":"Change labels of segments","tags":["Segments"],"parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridTagsInput"}}},"description":"Required by the server: ids."},"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"number"}},"required":["updated"]}}}},"400":{"description":"`validation` (message: ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/{segment}":{"delete":{"operationId":"segments_delete","summary":"Delete a segment no campaign, segment or automation names","tags":["Segments"],"description":"SE's Smazat segment: 204; 409 'conflict' with the message campaign, segment or automation while something names it.\n\nContract notes (cs):\n\nSpráva segmentu jako SE (audit SG-06, plný přístup `contacts`). DELETE → 204; 409 `conflict` se zprávou `campaign` (segment je v příjemcích kampaně), `segment` (odkazuje na něj podmínka jiného segmentu) nebo `automation` (podmínka uzlu automatizace); kontakty zůstávají. `to-list` (SE „Převést na seznam“): tělo `{ \"name\" }` (1 až 100 znaků), vznikne ruční seznam e-shopu segmentu s jeho kontakty, kterým se teď smí posílat (přihlášené, bez blokace a slabého souhlasu), jako potvrzení; hromadný zápis, nespustí automatizace. Odpověď 201 `{ \"listId\", \"name\", \"members\" }`, 409 `name` při obsazeném názvu seznamu. `recompute` (SE „Přepočítat segment“): statický segment si vezme nový snímek kontaktů, denní se počítá živě; odpověď detail. Zapnutí a vypnutí obnovy = PATCH `{ \"refresh\": \"daily\" | \"static\" }`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}}],"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"x-mcp-confirm":"delete","responses":{"204":{"description":"No content"},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"segments_show","summary":"Get a segment","tags":["Segments"],"description":"One segment with its definition tree.\n\nContract notes (cs):\n\n`SegmentDetail` = `SegmentSummary`, `definition` a `signatureHtml` (pokročilé nastavení: podpis vlastníka jako HTML, server ho před uložením čistí stejně jako obsah e-mailu: žádný `<script>`, atributy `on*`, `javascript:`; výchozí `\"\"`).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}}],"x-postarna-permission":{"module":"contacts","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_segment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentDetail"},"examples":{"segments-show":{"summary":"docs/api-examples/segments.json show","value":{"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":""}}}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"segments_update","summary":"Update a segment","tags":["Segments"],"description":"Changes a segment (the shop never changes).\n\nContract notes (cs):\n\nTělo `{ \"name\", \"publicName\"?, \"shopId\", \"refresh\"?, \"definition\", \"signatureHtml\"? }` (PATCH podmnožina; bez `refresh` je nový segment `static`, jako v SE „Automaticky obnovovat segment“ výchozí vypnuto). Chyby: 400 `name` (1 až 100 znaků), `publicName` (do 100 znaků), `signatureHtml` (do 5 000 znaků), `shop`, `refresh`, `definition…`; 409 `name` při obsazeném názvu. E-shop uloženého segmentu se nemění (400 `shop`), protože na něm stojí kampaně. Každé uložení statického segmentu udělá nový snímek.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"publicName":{"type":"string"},"shopId":{"type":"string"},"refresh":{"type":"string","enum":["static","daily"]},"definition":{"$ref":"#/components/schemas/SegmentGroup"},"signatureHtml":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels (Štítky)."}}}}}},"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"x-mcp-tool":"update_segment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentDetail"}}}},"400":{"description":"`validation` (message: definition, refresh, shop, signatureHtml, tags)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict` (message: name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/{segment}/members":{"get":{"operationId":"segments_members","summary":"List the members of a segment","tags":["Segments"],"description":"SE's detail of a segment (SG-07): its members as the contacts grid (?q=, ?state=, ?engagement=, ?sort=, paging; rows as GET /contacts): the stored snapshot of a static segment, the live definition otherwise.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/sort"},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"contacts","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContactListItem"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}}}},"400":{"description":"`validation` (message: q)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/{segment}/recompute":{"post":{"operationId":"segments_recompute","summary":"Recompute a segment now","tags":["Segments"],"description":"SE's Přepočítat segment: a static segment takes a new snapshot of its members now, a daily one is live anyway (computedAt moves); the detail.\n\nContract notes (cs):\n\nSpráva segmentu jako SE (audit SG-06, plný přístup `contacts`). DELETE → 204; 409 `conflict` se zprávou `campaign` (segment je v příjemcích kampaně), `segment` (odkazuje na něj podmínka jiného segmentu) nebo `automation` (podmínka uzlu automatizace); kontakty zůstávají. `to-list` (SE „Převést na seznam“): tělo `{ \"name\" }` (1 až 100 znaků), vznikne ruční seznam e-shopu segmentu s jeho kontakty, kterým se teď smí posílat (přihlášené, bez blokace a slabého souhlasu), jako potvrzení; hromadný zápis, nespustí automatizace. Odpověď 201 `{ \"listId\", \"name\", \"members\" }`, 409 `name` při obsazeném názvu seznamu. `recompute` (SE „Přepočítat segment“): statický segment si vezme nový snímek kontaktů, denní se počítá živě; odpověď detail. Zapnutí a vypnutí obnovy = PATCH `{ \"refresh\": \"daily\" | \"static\" }`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentDetail"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/segments/{segment}/to-list":{"post":{"operationId":"segments_to_list","summary":"Convert a segment into a manual list of its mailable contacts","tags":["Segments"],"description":"SE's Převést na seznam: body {name}; 201 {listId, name, members} with a new manual list of the segment's mailable contacts now (bulk: no automation starts); 409 'conflict' / 'name' for a taken list name.\n\nContract notes (cs):\n\nSpráva segmentu jako SE (audit SG-06, plný přístup `contacts`). DELETE → 204; 409 `conflict` se zprávou `campaign` (segment je v příjemcích kampaně), `segment` (odkazuje na něj podmínka jiného segmentu) nebo `automation` (podmínka uzlu automatizace); kontakty zůstávají. `to-list` (SE „Převést na seznam“): tělo `{ \"name\" }` (1 až 100 znaků), vznikne ruční seznam e-shopu segmentu s jeho kontakty, kterým se teď smí posílat (přihlášené, bez blokace a slabého souhlasu), jako potvrzení; hromadný zápis, nespustí automatizace. Odpověď 201 `{ \"listId\", \"name\", \"members\" }`, 409 `name` při obsazeném názvu seznamu. `recompute` (SE „Přepočítat segment“): statický segment si vezme nový snímek kontaktů, denní se počítá živě; odpověď detail. Zapnutí a vypnutí obnovy = PATCH `{ \"refresh\": \"daily\" | \"static\" }`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"segment","in":"path","required":true,"description":"Id of the segment (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"x-postarna-permission":{"module":"contacts","level":"full","keyScope":"full"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentToListResult"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict` (message: name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pst_ API key","description":"An API key of the company: Authorization: Bearer pst_... (Nastavení › Datové zdroje › API klíče). Scope read or full, roles of the key."},"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic as SmartEmailing: user name = e-mail of an active member of the company, password = the API key."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 for MCP clients (AI assistants) only: authorization code with PKCE S256, dynamic registration.","flows":{"authorizationCode":{"authorizationUrl":"https://www.postarna.cz/oauth/authorize","tokenUrl":"https://www.postarna.cz/oauth/token","refreshUrl":"https://www.postarna.cz/oauth/token","scopes":{"read":"Read only (routes whose permission level is read).","full":"Everything the member's roles allow."}}}}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.","schema":{"type":"string","format":"uuid"}},"page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number, from 1."},"pageSize":{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page, 1 to 100."},"q":{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Search text (case and diacritics insensitive)."},"sort":{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort fields separated by commas, \"-\" = descending, at most 3 (e.g. name,-id)."}},"headers":{"X-RateLimit-Limit":{"description":"Size of the bucket nearest to running out (2 500 per second bucket or 100 000 daily).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when that bucket is full again.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"401 unauthorized: missing, unknown, revoked, expired or idle API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"api_key"}}}}},"Forbidden":{"description":"403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"scope"}}}}},"RateLimited":{"description":"429 rate_limited: wait Retry-After seconds.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"per-second"}}}}}},"schemas":{"ContactListItem":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"status":{"type":"string","enum":["pending","subscribed","unsubscribed","bounced","complained","customer"]},"engagement":{"type":"string","enum":["A","B","C","D","E","N"]},"excluded":{"type":"boolean","description":"SE \"Vyloučené\": long inactive yet mailed often (recomputed weekly with the engagement)."},"shopId":{"type":["string","null"],"description":"Main e-shop (contacts.shop_id), null when unknown."},"suppressionReason":{"type":["string","null"],"enum":["invalid","manual","unsubscribed","hard_bounce","complaint","soft_bounce_limit",null],"description":"Set when the address is on the tenant suppression list."},"blacklisted":{"type":"boolean","description":"On the tenant's blacklist (\"Na blacklistu\"): a manual entry, or an entry of SmartEmailing's blacklist that keeps\nits own reason (migration 0180). Older servers leave it out: then suppressionReason 'manual' decides."},"blacklistedAt":{"type":["string","null"],"description":"When the address went on the blacklist (the suppression's time), null when it is not on it (\"Přidán na blacklist\")."},"state":{"type":"string","enum":["active","bounced","blacklisted"],"description":"SmartEmailing's 3-value contact state; older servers leave it out (contactState derives it)."},"createdAt":{"type":"string"},"extra":{"type":"object","additionalProperties":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"},{"type":"null"}]},"description":"Values of the extra columns asked for (ContactQuery.fields): dates as YYYY-MM-DD, times as ISO."}},"required":["id","email","firstName","lastName","status","engagement","excluded","shopId","suppressionReason","createdAt"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["conflict","count_mismatch","csrf","empty_segment","expired","forbidden","method_not_allowed","not_found","not_implemented","rate_limited","recently_sent","server","suppression_locked","unauthorized","unavailable","upstream","validation"],"description":"Stable machine readable code (see the error catalog in the guides)."},"message":{"type":"string","description":"The field or the reason (technical, not for people), e.g. \"email\", \"definition.1.0.listId\", \"name\"."},"params":{"type":"object","additionalProperties":true,"description":"Details: issues of a graph, expected and actual counts, retryAfter ..."}}}},"examples":[{"error":{"code":"validation","message":"email"}},{"error":{"code":"conflict","message":"version","params":{"current":4}}}]},"GridTagsInput":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids"],"description":"Bulk label change: add and remove, or tags = the new labels of every row."},"SegmentDetail":{"type":"object","properties":{"definition":{"$ref":"#/components/schemas/SegmentGroup"},"signatureHtml":{"type":"string","description":"Advanced setting: owner's signature as HTML, sanitized like e-mail content."},"id":{"type":"string"},"name":{"type":"string"},"publicName":{"type":"string","description":"Advanced setting (se-spec 01 §3): name on the unsubscribe page when the segment is used as a sendable list."},"shopId":{"type":"string","description":"Segments belong to one shop; only contacts whose main shop it is are evaluated."},"refresh":{"type":"string","enum":["static","daily"]},"matched":{"type":"number","description":"Contacts of the shop that meet the conditions, any status."},"mailable":{"type":"number","description":"Of those: subscribed, not suppressed, without weak consent."},"computedAt":{"type":"string"},"ruleCount":{"type":"number"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels (Štítky); absent from older servers."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["definition","signatureHtml","id","name","publicName","shopId","refresh","matched","mailable","computedAt","ruleCount","createdAt","updatedAt"]},"SegmentGroup":{"type":"object","additionalProperties":false,"description":"A segment definition: AND (all) / OR (any) groups nested at most 8 levels, at most 50 rules. An empty root matches every contact of the shop (a saved segment needs at least one rule); an empty subgroup is an error. Errors: 400 validation \"definition.<path>.<field>\" (path = indices from the root).","properties":{"type":{"const":"group"},"match":{"type":"string","enum":["all","any"],"description":"all = AND, any = OR."},"rules":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/SegmentGroup"},{"$ref":"#/components/schemas/SegmentRule_field"},{"$ref":"#/components/schemas/SegmentRule_list"},{"$ref":"#/components/schemas/SegmentRule_order_count"},{"$ref":"#/components/schemas/SegmentRule_order_value"},{"$ref":"#/components/schemas/SegmentRule_last_order"},{"$ref":"#/components/schemas/SegmentRule_engagement"},{"$ref":"#/components/schemas/SegmentRule_purpose"},{"$ref":"#/components/schemas/SegmentRule_custom_field"},{"$ref":"#/components/schemas/SegmentRule_campaign"},{"$ref":"#/components/schemas/SegmentRule_order_attribute"},{"$ref":"#/components/schemas/SegmentRule_segment"},{"$ref":"#/components/schemas/SegmentRule_list_label"},{"$ref":"#/components/schemas/SegmentRule_opens"},{"$ref":"#/components/schemas/SegmentRule_product_bought"},{"$ref":"#/components/schemas/SegmentRule_web_visit"},{"$ref":"#/components/schemas/SegmentRule_web_attribute"}]},"description":"Rules and subgroups."}},"required":["type","match","rules"],"examples":[{"type":"group","match":"any","rules":[{"type":"order_value","operator":"gte","amount":"2000","currency":"CZK","shopId":"1","days":"365"},{"type":"group","match":"all","rules":[{"type":"list","operator":"in","listId":"101"},{"type":"field","field":"lastOpenAt","operator":"in_last_days","value":"60"}]}]}]},"SegmentInput":{"type":"object","properties":{"name":{"type":"string"},"publicName":{"type":"string"},"shopId":{"type":"string"},"refresh":{"type":"string","enum":["static","daily"]},"definition":{"$ref":"#/components/schemas/SegmentGroup"},"signatureHtml":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels (Štítky)."}},"required":["name","shopId","refresh","definition"]},"SegmentPreview":{"type":"object","properties":{"matched":{"type":"number"},"mailable":{"type":"number"},"total":{"type":"number","description":"All contacts of the shop."}},"required":["matched","mailable","total"]},"SegmentRule_campaign":{"type":"object","description":"Delivered / opened / clicked a campaign (not_* also matches contacts that never got it); linkUrl narrows clicks to one link.","properties":{"type":{"const":"campaign"},"operator":{"type":"string","enum":["received","not_received","opened","not_opened","clicked","not_clicked"],"description":"Operator."},"campaignId":{"type":["string","null"],"description":"Campaign id; null only with received = an e-mail of any campaign."},"linkUrl":{"type":"string","description":"clicked / not_clicked only."},"days":{"type":["string","null"],"description":"Last N days or null."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","campaignId"],"examples":[{"type":"campaign","operator":"opened","campaignId":"121","days":null}]},"SegmentRule_custom_field":{"type":"object","description":"A custom field. kind must match the field type: text and textarea -> text, number -> number, date -> date, checkbox -> bool, select and radio -> choice, multi_checkbox -> multi_choice (400 definition.<path>.kind otherwise). Operators: text like the text fields, number gte/lte/eq/is_empty/is_not_empty, date like the date fields, bool is_true/is_false, choice is/is_not, multi_choice contains_any/contains_all/not_contains_any.","properties":{"type":{"const":"custom_field"},"fieldId":{"type":"string","description":"Custom field id (without cf:)."},"kind":{"type":"string","enum":["bool","choice","date","multi_choice","number","text"],"description":"Kind of the field type (see above)."},"operator":{"type":"string","description":"Operator for the kind."},"value":{"type":"string","description":"Value (string)."},"values":{"type":"array","items":{"type":"string"},"description":"Options (multi_choice)."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","fieldId","kind","operator"],"examples":[{"type":"custom_field","fieldId":"62","kind":"text","operator":"equals","value":"VIP"}]},"SegmentRule_engagement":{"type":"object","description":"Engagement level A (best) to E, N = new.","properties":{"type":{"const":"engagement"},"operator":{"type":"string","enum":["in","not_in"],"description":"Operator."},"values":{"type":"array","items":{"type":"string","enum":["A","B","C","D","E","N"],"description":"Level."},"description":"Levels.","minItems":1,"uniqueItems":true},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","values"],"examples":[{"type":"engagement","operator":"in","values":["A","B"]}]},"SegmentRule_field":{"type":"object","description":"A contact field compared with a value. Text operators ignore case and diacritics; date operators count calendar days of the company. Text fields: email, firstName, lastName, city, company, companyId, phone, mobile, street, postalCode, note, country. Enum fields: status (pending/subscribed/unsubscribed/bounced/complained/customer), gender (f/m), language (cs/sk), source (erp_order/signup_form/import/api/manual/shoptet/smartemailing), consentBasis (soft_opt_in_customer/double_opt_in/imported/none). Date fields: createdAt, lastOpenAt, lastClickAt, lastSentAt, statusAt, consentAt.","properties":{"type":{"const":"field"},"field":{"type":"string","enum":["email","firstName","lastName","city","company","companyId","phone","mobile","street","postalCode","note","country","status","gender","language","source","consentBasis","createdAt","lastOpenAt","lastClickAt","lastSentAt","statusAt","consentAt"],"description":"Contact field."},"operator":{"type":"string","enum":["contains","not_contains","equals","not_equals","starts_with","ends_with","is_empty","is_not_empty","is","is_not","in_last_days","not_in_last_days","before","after","until","since"],"description":"Text: contains, not_contains, equals, not_equals, starts_with, ends_with, is_empty, is_not_empty; enum: is, is_not; date: in_last_days, not_in_last_days, before, after, until, since, is_empty, is_not_empty."},"value":{"type":"string","description":"Always a string: the text, the enum value, a number of days (\"30\") for in_last_days / not_in_last_days, or a date YYYY-MM-DD for before / after; \"\" for is_empty / is_not_empty."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","field","operator","value"],"examples":[{"type":"field","field":"lastOpenAt","operator":"in_last_days","value":"60"}]},"SegmentRule_last_order":{"type":"object","description":"The last completed order: within / older than N days, or before / after a date.","properties":{"type":{"const":"last_order"},"operator":{"type":"string","enum":["in_last_days","older_than_days","before","after"],"description":"Operator."},"value":{"type":"string","description":"Days \"1\" to \"3650\" or a date YYYY-MM-DD."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."},"shopId":{"type":["string","null"],"description":"Only orders of this shop (null = any)."},"currency":{"type":["string","null"],"description":"Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set)."}},"additionalProperties":false,"required":["type","operator","value"],"examples":[{"type":"last_order","operator":"older_than_days","value":"180"}]},"SegmentRule_list":{"type":"object","description":"Membership in a list. in / not_in = confirmed or unconfirmed member; status_is compares the exact state; added_before / added_after compare the day the contact was added; longer_than_days / shorter_than_days: in the list longer / shorter than N days.","properties":{"type":{"const":"list"},"operator":{"type":"string","enum":["in","not_in","added_before","added_after","status_is","longer_than_days","shorter_than_days"],"description":"Operator."},"listId":{"type":"string","description":"List id."},"value":{"type":"string","description":"status_is: confirmed, unconfirmed, unsubscribed, removed; added_*: YYYY-MM-DD; *_than_days: days \"1\" to \"3650\"."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","listId"],"examples":[{"type":"list","operator":"in","listId":"101"}]},"SegmentRule_list_label":{"type":"object","description":"Confirmed or unconfirmed member of any list with this label.","properties":{"type":{"const":"list_label"},"operator":{"type":"string","enum":["in"],"description":"Operator."},"label":{"type":"string","description":"Label, 1 to 40."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","label"],"examples":[{"type":"list_label","operator":"in","label":"vip"}]},"SegmentRule_opens":{"type":"object","description":"Number of the contact's e-mails (campaigns and automations) with an open.","properties":{"type":{"const":"opens"},"operator":{"type":"string","enum":["eq","gt","lt","gte","lte"],"description":"Operator."},"value":{"type":"string","description":"Count \"0\" to \"100000\"."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","value"],"examples":[{"type":"opens","operator":"gte","value":"3","days":"90"}]},"SegmentRule_order_attribute":{"type":"object","description":"A completed order has an item whose product code, category, brand or another item attribute (as stored on the order item) equals the value; with scope order an attribute of the order itself.","properties":{"type":{"const":"order_attribute"},"operator":{"type":"string","enum":["is"],"description":"Operator."},"scope":{"type":"string","enum":["item","order"],"description":"item (default) or order.","default":"item"},"attribute":{"type":"string","description":"item: productCode, category, brand or any attribute name; order: status, companyId, deliveryCity, deliveryCountry, deliveryZip, deliveryCompany."},"value":{"type":"string","description":"Exact value, at most 200 characters."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."},"shopId":{"type":["string","null"],"description":"Only orders of this shop (null = any)."},"currency":{"type":["string","null"],"description":"Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set)."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."}},"additionalProperties":false,"required":["type","operator","attribute","value"],"examples":[{"type":"order_attribute","operator":"is","attribute":"brand","value":"Example"}]},"SegmentRule_order_count":{"type":"object","description":"Number of completed orders.","properties":{"type":{"const":"order_count"},"operator":{"type":"string","enum":["gte","lte","eq"],"description":"Operator."},"value":{"type":"string","description":"Count \"0\" to \"100000\"."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."},"shopId":{"type":["string","null"],"description":"Only orders of this shop (null = any)."},"currency":{"type":["string","null"],"description":"Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set)."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."}},"additionalProperties":false,"required":["type","operator","value"],"examples":[{"type":"order_count","operator":"gte","value":"2","shopId":null,"currency":null,"days":"365"}]},"SegmentRule_order_value":{"type":"object","description":"Sum of completed orders with VAT in one currency (CZK and EUR are never added up).","properties":{"type":{"const":"order_value"},"operator":{"type":"string","enum":["gte","lte"],"description":"Operator."},"amount":{"type":"string","description":"Amount, at most 2 decimals, e.g. \"1500.50\"."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."},"shopId":{"type":["string","null"],"description":"Only orders of this shop (null = any)."},"currency":{"type":["string","null"],"description":"Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set)."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."}},"additionalProperties":false,"required":["type","operator","amount","currency"],"examples":[{"type":"order_value","operator":"gte","amount":"2000","currency":"CZK","shopId":"1","days":"365"}]},"SegmentRule_product_bought":{"type":"object","description":"A completed order has an item whose name contains the text or whose product code equals it (case and diacritics ignored).","properties":{"type":{"const":"product_bought"},"operator":{"type":"string","enum":["is"],"description":"Operator."},"value":{"type":"string","description":"Part of the name or the code, at most 200."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."},"shopId":{"type":["string","null"],"description":"Only orders of this shop (null = any)."},"currency":{"type":["string","null"],"description":"Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set)."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."}},"additionalProperties":false,"required":["type","operator","value"],"examples":[{"type":"product_bought","operator":"is","value":"Espresso","days":"30"}]},"SegmentRule_purpose":{"type":"object","description":"A valid (not withdrawn, within its validity) consent with a purpose of processing.","properties":{"type":{"const":"purpose"},"operator":{"type":"string","enum":["has","not_has"],"description":"Operator."},"purposeId":{"type":"string","description":"Purpose id."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","purposeId"],"examples":[{"type":"purpose","operator":"has","purposeId":"51"}]},"SegmentRule_segment":{"type":"object","description":"Member of another segment of the same shop (never itself; chains at most 5 deep, no cycles).","properties":{"type":{"const":"segment"},"operator":{"type":"string","enum":["in","not_in","added_before","added_after"],"description":"Operator."},"segmentId":{"type":"string","description":"Segment id."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator","segmentId"],"examples":[{"type":"segment","operator":"not_in","segmentId":"91"}]},"SegmentRule_web_attribute":{"type":"object","description":"A page visit whose attribute matches: visitType = the page type, other names = the visit's own attributes; gt to lte compare numbers.","properties":{"type":{"const":"web_attribute"},"attribute":{"type":"string","description":"Attribute name."},"operator":{"type":"string","enum":["is","starts_with","gt","gte","lt","lte"],"description":"Operator."},"value":{"type":"string","description":"At most 200 (a number for gt to lte)."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","attribute","operator","value"],"examples":[{"type":"web_attribute","attribute":"visitType","operator":"is","value":"product"}]},"SegmentRule_web_visit":{"type":"object","description":"A page visit recorded by the shop's script or the API; any = any page.","properties":{"type":{"const":"web_visit"},"operator":{"type":"string","enum":["any","is","starts_with","contains"],"description":"Operator."},"url":{"type":"string","description":"Not with any; at most 2 000."},"days":{"type":["string","null"],"description":"Only the last N days, \"1\" to \"3650\" (null = any time)."},"negate":{"type":"boolean","description":"true = the rule must NOT hold (SmartEmailing \"Neplatí, že\")."}},"additionalProperties":false,"required":["type","operator"],"examples":[{"type":"web_visit","operator":"contains","url":"/kava/","days":"30"}]},"SegmentSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicName":{"type":"string","description":"Advanced setting (se-spec 01 §3): name on the unsubscribe page when the segment is used as a sendable list."},"shopId":{"type":"string","description":"Segments belong to one shop; only contacts whose main shop it is are evaluated."},"refresh":{"type":"string","enum":["static","daily"]},"matched":{"type":"number","description":"Contacts of the shop that meet the conditions, any status."},"mailable":{"type":"number","description":"Of those: subscribed, not suppressed, without weak consent."},"computedAt":{"type":"string"},"ruleCount":{"type":"number"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels (Štítky); absent from older servers."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","publicName","shopId","refresh","matched","mailable","computedAt","ruleCount","createdAt","updatedAt"]},"SegmentToListResult":{"type":"object","properties":{"listId":{"type":"string"},"name":{"type":"string"},"members":{"type":"number"}},"required":["listId","name","members"],"description":"POST /segments/{id}/to-list: the new list and how many contacts it got."}}}}