{"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":"Statistics","x-displayName":"Statistics","description":"E-mail statistics of campaigns and automations, dashboard, conversions."}],"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}/conversions":{"get":{"operationId":"conversions_summary","summary":"Conversions summary","tags":["Statistics"],"description":"Conversions per kind and currency, optionally of one campaign or automation and in [from, to).\n\nContract notes (cs):\n\n`campaignId`, `automationId`, `from`, `to` → `{items: [{kind, currency, orders, totalWithVat, totalWithoutVat}]}`, zvlášť po druhu a měně. Stornované a smazané objednávky se nepočítají. Konverze: poslední proklik stejného kontaktu nejvýš 5 dní před objednávkou, do 24 h přímá, potom asistovaná.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automationId","in":"query","required":false,"schema":{"type":"string"}},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","description":"Per kind and currency: kind, currency, orders, revenue (decimal string)."}}}}}}},"400":{"description":"`validation`","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}/dashboard":{"get":{"operationId":"dashboard","summary":"Dashboard numbers","tags":["Statistics"],"description":"Dashboard: contacts (total, subscribed, added and lost in 30 days, daily trend) and e-mails of the last 30 days against the 30 days before.\n\nContract notes (cs):\n\n`DashboardData` (SE dashboard: Přehled účtu, poslední kontakt a e-mail, statistiky rozesílek 30 dní): `days` (30), `contacts` (`total`, `subscribed`, `added` a `lost` za 30 dní, `trend` po dnech `{date, added, lost}` = nové kontakty a adresy nově v potlačení), `lastContact` `{id, email, source, createdAt}`, `emails` (`current` a `previous` = EmailMetrics e-mailů kampaní a automatizací odeslaných za posledních 30 dní a za 30 dní před tím, `daily` `{date, sent, unsubscribed}`), `lastEmail` `{kind, campaignId, automationId, nodeKey, name, nodeName, sentAt}`. Části, které role člena nesmí číst, jsou `null` (`contacts` a `lastContact` bez modulu kontaktů, `emails` a `lastEmail` bez modulu kampaní). Bez fakturačních ukazatelů.","parameters":[{"$ref":"#/components/parameters/tenant"}],"x-postarna-permission":{"module":null,"level":"read","keyScope":"read or full"},"x-mcp-tool":"get_dashboard","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/stats/automations/{automation_id}":{"get":{"operationId":"stats_automation","summary":"Statistics of an automation","tags":["Statistics"],"description":"E-mail statistics of an automation (or of one e-mail node).\n\nContract notes (cs):\n\n`EmailStatsDetail`: hlavička (`kind`, `campaignId`, `automationId`, `nodeKey`, `name`, `subject`, `shopId`, `status`, `sentAt`, `nodes` = e-mailové uzly automatizace `{key, name}`), `totals: EmailMetrics`, `providers` (EmailMetrics a `provider` po skupinách poskytovatelů schránek, nejvýš 15), `timeline` (po dnech: `date`, `opens`, `clicks`, `unsubscribed`), `links` (`url`, `clicks`, `uniqueClicks`, nejvýš 50).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"First day YYYY-MM-DD."},{"name":"node","in":"query","required":false,"schema":{"type":"string"},"description":"E-mail node key."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Last day YYYY-MM-DD."}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_automation_stats","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailStatsDetail"}}}},"400":{"description":"`validation` (message: node, to)","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}/stats/automations/{automation_id}/activity":{"get":{"operationId":"stats_automation_activity","summary":"Activity of an automation over time","tags":["Statistics"],"description":"Contract notes (cs):\n\n`?tab=opened|clicked|unsubscribed|bounced&q=&from=&to=&node=&page=&pageSize=` → `Page<StatsActivity>`: jeden řádek na e-mail se záložkou, nejnovější první: `sendId`, `contactId`, `email`, `firstAt`, `lastAt`, `opens`, `clicks`, `type` (`open`, `click`, `unsubscribe`, `complaint`, `hard`, `soft`), `source` (`ses`, `web`, `fbl`), `links` (u prokliků nejvýš 5), `detail` (podtyp vrácení). Počet řádků záložky odpovídá metrice (`opened` = `uniqueOpens`, `clicked` = `uniqueClicks`); záložka Odhlášeno ukazuje i stížnosti.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/q"},{"name":"tab","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StatsActivity"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}}}},"400":{"description":"`validation` (message: node, q, tab, to)","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}/stats/automations/{automation_id}/conversions":{"get":{"operationId":"stats_automation_conversions","summary":"Conversions (orders) of an automation","tags":["Statistics"],"description":"Contract notes (cs):\n\n`EmailConversions`: `available` (false = server nemá zdroj konverzí, UI to napíše místo nul), `directHours` (24), `assistedDays` (5), `currencies` = jedna položka na měnu `{currency, direct: {orders, revenue, revenueWithoutVat}, assisted: {...}}` (desetinné řetězce, CZK a EUR nikdy dohromady), `orders` (nejvýš 100: `orderId`, `code`, `contactId`, `email`, `kind` `direct` nebo `assisted`, `clickedAt`, `orderedAt`, `currency`, `totalWithVat`, `totalWithoutVat`). Zdroj je párování objednávek (`core/conversions.py`): objednávka stejného kontaktu po jeho posledním prokliku, do 24 hodin přímá, od 24 hodin do 5 dní asistovaná; stornované a smazané se nepočítají. Období se na konverze neuplatňuje.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailConversions"}}}},"400":{"description":"`validation` (message: node, to)","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}/stats/automations/{automation_id}/heatmap":{"get":{"operationId":"stats_automation_heatmap","summary":"Click map of an automation","tags":["Statistics"],"description":"The same for one e-mail node of an automation (?node=, the template of the node); without a node no HTML.\n\nContract notes (cs):\n\n`{html, links}`: HTML e-mailu (u automatizace šablona uzlu `?node=`, bez uzlu prázdné) a prokliky každého odkazu. UI ho zobrazí v rámu bez skriptů a nad odkazy napíše podíl prokliků.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailHeatmap"}}}},"400":{"description":"`validation` (message: node, to)","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}/stats/automations/{automation_id}/recipients":{"get":{"operationId":"stats_automation_recipients","summary":"Recipients of an automation with their events (JSON or CSV)","tags":["Statistics"],"description":"Contract notes (cs):\n\n`?tab=all|opened|clicked|conversions|unsubscribed|bounced&q=&page=&pageSize=` + filtry reportu + vlastní Filtry tabulky (`opened`, `clicked`, `purchased`, `reopened`, `hard` = 1 nebo 0, `state` = received | processing | shipped | cancelled | unknown, `reason`) → `Page` řádků záložky (příjemci s ANO / NE a cenami po měnách, otevření s opakováním a klientem, jednotlivé prokliky, spárované objednávky se stavem a zbožím, odhlášení s důvodem a komentářem, vrácení s odpovědí serveru). `?format=csv` vrátí celou tabulku jako CSV (UTF-8 s BOM, středníky, buňka nikdy jako vzorec).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]},"description":"csv = a CSV file (UTF-8 with BOM, semicolons)."},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"humans","in":"query","required":false,"schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/q"},{"name":"rows","in":"query","required":false,"schema":{"type":"string"}},{"name":"tab","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"vat","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"JSON, or CSV with format=csv","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"`validation` (message: engagement, node, q, tab, to)","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}/stats/automations/{automation_id}/report":{"get":{"operationId":"stats_automation_report","summary":"Report of an automation (JSON or CSV)","tags":["Statistics"],"description":"Contract notes (cs):\n\nDetail jako SE (`core/stats_report.py`), filtry `?engagement=A,B,…` (skupiny angažovanosti, prázdné = všechny), `?humans=1` (bez otevření přes proxy obrázků webmailu), `?vat=1` (peníze s DPH, jinak bez), u automatizace `?node=`. 400 `validation` / `engagement`, `humans`, `vat`. `EmailStatsReport`: hlavička (`name`, `status`, `startedAt`, `completedAt`, `shopId`, `nodes`), `filters`, `firstSentAt`, `lastSentAt`, `totals` (EmailMetrics + `orders`, `orderRate`, `reopeners`, `reopenRate`), `baseline` (poměry e-mailů účtu za 30 dní před kampaní, u automatizace před dneškem; `sent` = průměrná velikost jednorázové kampaně; `null` bez dat), `days` (po dnech od prvního e-mailu, nejvýš 31: unikátní otevření, prokliky, odhlášení, vrácení), `domains` (`sent`, `opened`, `clicked`, `unsubscribed`, `bounced`, `buyers`; `{name, count}`, `name` '' = zbytek), `clients` a `systems` (`opened`, `clicked`), `links` (`url`, `clicks`, `uniqueClicks`, `share`), `unsubscribeReasons` (`too_often`, `not_relevant`, `annoying`, `not_signed_up`, `spam_report`, `other`, `custom`, `none`, `misc`), `bounceReasons` (`mailbox_full`, `spam_filter`, `no_address`, `transfer_error`, `temporary`, `server_error`, `mx_error`, `greylisted`, `suppressed`, `other`), `bounceSplit`, `revenue` (po měnách: objednávky, přímé a asistované, průměr, obrat e-shopu stejné měny od prvního e-mailu do 5 dní po posledním a podíl), `revenueDays`, `conversionLinks`, `products` (prodané kusy s obrázkem), `engagementSpend`, `topSpenders`. CZK a EUR nikdy dohromady.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automation_id","in":"path","required":true,"description":"Id of the automation (string of digits).","schema":{"type":"string"}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"humans","in":"query","required":false,"schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"vat","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailStatsReport"}}}},"400":{"description":"`validation` (message: engagement, node, to)","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}/stats/campaigns/{campaign_id}":{"get":{"operationId":"stats_campaign","summary":"Statistics of a campaign","tags":["Statistics"],"description":"E-mail statistics of a campaign: totals, rates (base: sent), providers, daily timeline, links.\n\nContract notes (cs):\n\n`EmailStatsDetail`: hlavička (`kind`, `campaignId`, `automationId`, `nodeKey`, `name`, `subject`, `shopId`, `status`, `sentAt`, `nodes` = e-mailové uzly automatizace `{key, name}`), `totals: EmailMetrics`, `providers` (EmailMetrics a `provider` po skupinách poskytovatelů schránek, nejvýš 15), `timeline` (po dnech: `date`, `opens`, `clicks`, `unsubscribed`), `links` (`url`, `clicks`, `uniqueClicks`, nejvýš 50).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"First day YYYY-MM-DD."},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Last day YYYY-MM-DD."}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_campaign_stats","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailStatsDetail"}}}},"400":{"description":"`validation` (message: to)","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}/stats/campaigns/{campaign_id}/activity":{"get":{"operationId":"stats_campaign_activity","summary":"Activity of a campaign over time","tags":["Statistics"],"description":"Who opened, clicked, unsubscribed or bounced (tab).\n\nContract notes (cs):\n\n`?tab=opened|clicked|unsubscribed|bounced&q=&from=&to=&node=&page=&pageSize=` → `Page<StatsActivity>`: jeden řádek na e-mail se záložkou, nejnovější první: `sendId`, `contactId`, `email`, `firstAt`, `lastAt`, `opens`, `clicks`, `type` (`open`, `click`, `unsubscribe`, `complaint`, `hard`, `soft`), `source` (`ses`, `web`, `fbl`), `links` (u prokliků nejvýš 5), `detail` (podtyp vrácení). Počet řádků záložky odpovídá metrice (`opened` = `uniqueOpens`, `clicked` = `uniqueClicks`); záložka Odhlášeno ukazuje i stížnosti.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"First day YYYY-MM-DD."},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Search text."},{"name":"tab","in":"query","required":false,"schema":{"type":"string","enum":["opened","clicked","unsubscribed","bounced"]},"description":"Tab."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Last day YYYY-MM-DD."}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_campaign_activity","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StatsActivity"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}}}},"400":{"description":"`validation` (message: q, tab, to)","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}/stats/campaigns/{campaign_id}/conversions":{"get":{"operationId":"stats_campaign_conversions","summary":"Conversions (orders) of a campaign","tags":["Statistics"],"description":"Orders after clicks of the campaign (direct within 24 hours, assisted), per currency.\n\nContract notes (cs):\n\n`EmailConversions`: `available` (false = server nemá zdroj konverzí, UI to napíše místo nul), `directHours` (24), `assistedDays` (5), `currencies` = jedna položka na měnu `{currency, direct: {orders, revenue, revenueWithoutVat}, assisted: {...}}` (desetinné řetězce, CZK a EUR nikdy dohromady), `orders` (nejvýš 100: `orderId`, `code`, `contactId`, `email`, `kind` `direct` nebo `assisted`, `clickedAt`, `orderedAt`, `currency`, `totalWithVat`, `totalWithoutVat`). Zdroj je párování objednávek (`core/conversions.py`): objednávka stejného kontaktu po jeho posledním prokliku, do 24 hodin přímá, od 24 hodin do 5 dní asistovaná; stornované a smazané se nepočítají. Období se na konverze neuplatňuje.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_campaign_conversions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailConversions"}}}},"400":{"description":"`validation` (message: to)","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}/stats/campaigns/{campaign_id}/heatmap":{"get":{"operationId":"stats_campaign_heatmap","summary":"Click map of a campaign","tags":["Statistics"],"description":"SE \"Heatmapa prokliků\": the campaign's HTML (merge tags unfilled, the UI shows it in a sandboxed frame without scripts) and the clicks per link of its e-mails.\n\nContract notes (cs):\n\n`{html, links}`: HTML e-mailu (u automatizace šablona uzlu `?node=`, bez uzlu prázdné) a prokliky každého odkazu. UI ho zobrazí v rámu bez skriptů a nad odkazy napíše podíl prokliků.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailHeatmap"}}}},"400":{"description":"`validation` (message: to)","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}/stats/campaigns/{campaign_id}/recipients":{"get":{"operationId":"stats_campaign_recipients","summary":"Recipients of a campaign with their events (JSON or CSV)","tags":["Statistics"],"description":"Contract notes (cs):\n\n`?tab=all|opened|clicked|conversions|unsubscribed|bounced&q=&page=&pageSize=` + filtry reportu + vlastní Filtry tabulky (`opened`, `clicked`, `purchased`, `reopened`, `hard` = 1 nebo 0, `state` = received | processing | shipped | cancelled | unknown, `reason`) → `Page` řádků záložky (příjemci s ANO / NE a cenami po měnách, otevření s opakováním a klientem, jednotlivé prokliky, spárované objednávky se stavem a zbožím, odhlášení s důvodem a komentářem, vrácení s odpovědí serveru). `?format=csv` vrátí celou tabulku jako CSV (UTF-8 s BOM, středníky, buňka nikdy jako vzorec).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]},"description":"csv = a CSV file (UTF-8 with BOM, semicolons)."},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"humans","in":"query","required":false,"schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/q"},{"name":"rows","in":"query","required":false,"schema":{"type":"string"}},{"name":"tab","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"vat","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"JSON, or CSV with format=csv","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"`validation` (message: engagement, q, tab, to)","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}/stats/campaigns/{campaign_id}/report":{"get":{"operationId":"stats_campaign_report","summary":"Report of a campaign (JSON or CSV)","tags":["Statistics"],"description":"Contract notes (cs):\n\nDetail jako SE (`core/stats_report.py`), filtry `?engagement=A,B,…` (skupiny angažovanosti, prázdné = všechny), `?humans=1` (bez otevření přes proxy obrázků webmailu), `?vat=1` (peníze s DPH, jinak bez), u automatizace `?node=`. 400 `validation` / `engagement`, `humans`, `vat`. `EmailStatsReport`: hlavička (`name`, `status`, `startedAt`, `completedAt`, `shopId`, `nodes`), `filters`, `firstSentAt`, `lastSentAt`, `totals` (EmailMetrics + `orders`, `orderRate`, `reopeners`, `reopenRate`), `baseline` (poměry e-mailů účtu za 30 dní před kampaní, u automatizace před dneškem; `sent` = průměrná velikost jednorázové kampaně; `null` bez dat), `days` (po dnech od prvního e-mailu, nejvýš 31: unikátní otevření, prokliky, odhlášení, vrácení), `domains` (`sent`, `opened`, `clicked`, `unsubscribed`, `bounced`, `buyers`; `{name, count}`, `name` '' = zbytek), `clients` a `systems` (`opened`, `clicked`), `links` (`url`, `clicks`, `uniqueClicks`, `share`), `unsubscribeReasons` (`too_often`, `not_relevant`, `annoying`, `not_signed_up`, `spam_report`, `other`, `custom`, `none`, `misc`), `bounceReasons` (`mailbox_full`, `spam_filter`, `no_address`, `transfer_error`, `temporary`, `server_error`, `mx_error`, `greylisted`, `suppressed`, `other`), `bounceSplit`, `revenue` (po měnách: objednávky, přímé a asistované, průměr, obrat e-shopu stejné měny od prvního e-mailu do 5 dní po posledním a podíl), `revenueDays`, `conversionLinks`, `products` (prodané kusy s obrázkem), `engagementSpend`, `topSpenders`. CZK a EUR nikdy dohromady.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"campaign_id","in":"path","required":true,"description":"Id of the campaign (string of digits).","schema":{"type":"string"}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"humans","in":"query","required":false,"schema":{"type":"string"}},{"name":"node","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"End of the period (YYYY-MM-DD local day, or ISO time where noted)."},{"name":"vat","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"campaigns","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailStatsReport"}}}},"400":{"description":"`validation` (message: engagement, to)","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}/stats/emails":{"get":{"operationId":"stats_emails","summary":"E-mail statistics of campaigns and automations","tags":["Statistics"],"description":"Sent campaigns and automation e-mails with their metrics, newest first.\n\nContract notes (cs):\n\n`?q=&kind=campaign|automation&shop=&ref=&name=&sentFrom=&sentTo=&sort=&page=&pageSize=` (`ref` = ID kampaně nebo automatizace, `name` = část názvu bez diakritiky; řazení `id`, `name`, `sentAt`, `sent`, `opens`, `uniqueOpens`, `openRate`, …) → `Page<EmailStatsItem>`: kampaně, které začaly odesílat, a e-mailové uzly automatizací, které něco odeslaly, nejnovější první. `id` = `c<id kampaně>` nebo `a<id automatizace>:<klíč uzlu>`, `kind`, `campaignId`, `automationId`, `nodeKey`, `name`, `nodeName`, `subject` (u automatizace předmět šablony uzlu), `shopId`, `status`, `sentAt` (začátek odesílání, u automatizace první e-mail uzlu), `stats: EmailMetrics`. Hledání bez diakritiky v názvu, uzlu a předmětu.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"automationIds","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["campaign","automation"]},"description":"campaign or automation."},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Search text."},{"name":"ref","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":"campaigns","level":"read","keyScope":"read or full"},"x-mcp-tool":"list_email_stats","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailStatsPage"}}}},"400":{"description":"`validation` (message: automationIds, countTo, kind, name, q, sentTo, sort)","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":{"ConversionCurrency":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"direct":{"$ref":"#/components/schemas/ConversionPart"},"assisted":{"$ref":"#/components/schemas/ConversionPart"}},"required":["currency","direct","assisted"],"description":"One currency: CZK and EUR are never added up or converted."},"ConversionOrder":{"type":"object","properties":{"orderId":{"type":"string"},"code":{"type":"string"},"contactId":{"type":["string","null"]},"email":{"type":["string","null"]},"kind":{"type":"string","enum":["direct","assisted"]},"clickedAt":{"type":"string"},"orderedAt":{"type":"string"},"currency":{"$ref":"#/components/schemas/Currency"},"totalWithVat":{"type":["string","null"]},"totalWithoutVat":{"type":["string","null"]}},"required":["orderId","code","contactId","email","kind","clickedAt","orderedAt","currency","totalWithVat","totalWithoutVat"]},"ConversionPart":{"type":"object","properties":{"orders":{"type":"number"},"revenue":{"type":["string","null"]},"revenueWithoutVat":{"type":["string","null"]}},"required":["orders","revenue","revenueWithoutVat"]},"Currency":{"type":"string","enum":["CZK","EUR"]},"DashboardData":{"type":"object","properties":{"days":{"type":"number"},"contacts":{"type":["object","null"],"properties":{"total":{"type":"number"},"subscribed":{"type":"number"},"added":{"type":"number"},"lost":{"type":"number"},"trend":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"added":{"type":"number"},"lost":{"type":"number"}},"required":["date","added","lost"]}}},"required":["total","subscribed","added","lost","trend"],"description":"null when the member's roles cannot read contacts."},"lastContact":{"type":["object","null"],"properties":{"id":{"type":"string"},"email":{"type":"string"},"source":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","email","source","createdAt"]},"emails":{"type":["object","null"],"properties":{"current":{"$ref":"#/components/schemas/EmailMetrics"},"previous":{"$ref":"#/components/schemas/EmailMetrics"},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"sent":{"type":"number"},"unsubscribed":{"type":"number"}},"required":["date","sent","unsubscribed"]}}},"required":["current","previous","daily"],"description":"null when the member's roles cannot read campaigns."},"lastEmail":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["campaign","automation"]},"campaignId":{"type":["string","null"]},"automationId":{"type":["string","null"]},"nodeKey":{"type":["string","null"]},"name":{"type":"string"},"nodeName":{"type":"string"},"sentAt":{"type":"string"}},"required":["kind","campaignId","automationId","nodeKey","name","nodeName","sentAt"]}},"required":["days","contacts","lastContact","emails","lastEmail"]},"EmailConversions":{"type":"object","properties":{"available":{"type":"boolean","description":"false = no conversion provider yet (the tab says so instead of showing zeros)."},"directHours":{"type":"number"},"assistedDays":{"type":"number"},"currencies":{"type":"array","items":{"$ref":"#/components/schemas/ConversionCurrency"}},"orders":{"type":"array","items":{"$ref":"#/components/schemas/ConversionOrder"}}},"required":["available","directHours","assistedDays","currencies","orders"]},"EmailHeatmap":{"type":"object","properties":{"html":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"}},"required":["url","clicks","uniqueClicks"]}}},"required":["html","links"],"description":"SE \"Heatmapa prokliků\": the e-mail's HTML and the clicks of every link."},"EmailMetrics":{"type":"object","properties":{"sent":{"type":"number"},"delivered":{"type":"number","description":"sent - undelivered"},"undelivered":{"type":"number","description":"Hard or soft bounce (SE \"Nedoručeno\")."},"bounced":{"type":"number"},"softBounced":{"type":"number"},"opens":{"type":"number"},"uniqueOpens":{"type":"number"},"repeatedOpens":{"type":"number"},"machineOpens":{"type":"number","description":"E-mails whose pixel only a machine fetched (Apple Mail Privacy Protection, security gateways): whether a person\nread them is unknown, so they are in no open count or rate."},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"},"unsubscribed":{"type":"number"},"complained":{"type":"number"},"queued":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"openRate":{"type":"number"},"ctr":{"type":"number"},"ctor":{"type":"number"},"unsubscribeRate":{"type":"number"},"bounceRate":{"type":"number"},"complaintRate":{"type":"number"},"deliveryRate":{"type":"number","description":"delivered / sent"}},"required":["sent","delivered","undelivered","bounced","softBounced","opens","uniqueOpens","repeatedOpens","machineOpens","clicks","uniqueClicks","unsubscribed","complained","queued","failed","skipped","openRate","ctr","ctor","unsubscribeRate","bounceRate","complaintRate","deliveryRate"],"description":"Counts of e-mails and their events (server core/stats.py). Rates as SmartEmailing: openRate, unsubscribeRate and\ncomplaintRate over the delivered e-mails, ctr and bounceRate over the sent ones; ctor = unique clicks / unique opens.\nTest e-mails never count."},"EmailStatsDetail":{"type":"object","properties":{"kind":{"type":"string","enum":["campaign","automation"]},"campaignId":{"type":["string","null"]},"automationId":{"type":["string","null"]},"nodeKey":{"type":["string","null"]},"name":{"type":"string"},"subject":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string"},"sentAt":{"type":["string","null"]},"nodes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"]}},"totals":{"$ref":"#/components/schemas/EmailMetrics"},"providers":{"type":"array","items":{"type":"object","properties":{"sent":{"type":"number"},"delivered":{"type":"number","description":"sent - undelivered"},"undelivered":{"type":"number","description":"Hard or soft bounce (SE \"Nedoručeno\")."},"bounced":{"type":"number"},"softBounced":{"type":"number"},"opens":{"type":"number"},"uniqueOpens":{"type":"number"},"repeatedOpens":{"type":"number"},"machineOpens":{"type":"number","description":"E-mails whose pixel only a machine fetched (Apple Mail Privacy Protection, security gateways): whether a person\nread them is unknown, so they are in no open count or rate."},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"},"unsubscribed":{"type":"number"},"complained":{"type":"number"},"queued":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"openRate":{"type":"number"},"ctr":{"type":"number"},"ctor":{"type":"number"},"unsubscribeRate":{"type":"number"},"bounceRate":{"type":"number"},"complaintRate":{"type":"number"},"deliveryRate":{"type":"number","description":"delivered / sent"},"provider":{"type":"string"}},"required":["sent","delivered","undelivered","bounced","softBounced","opens","uniqueOpens","repeatedOpens","machineOpens","clicks","uniqueClicks","unsubscribed","complained","queued","failed","skipped","openRate","ctr","ctor","unsubscribeRate","bounceRate","complaintRate","deliveryRate","provider"]}},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/StatsDay"}},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"}},"required":["url","clicks","uniqueClicks"]}}},"required":["kind","campaignId","automationId","nodeKey","name","subject","shopId","status","sentAt","nodes","totals","providers","timeline","links"]},"EmailStatsItem":{"type":"object","properties":{"id":{"type":"string","description":"c<campaign id> or a<automation id>:<node key>"},"kind":{"type":"string","enum":["campaign","automation"]},"campaignId":{"type":["string","null"]},"automationId":{"type":["string","null"]},"nodeKey":{"type":["string","null"]},"name":{"type":"string"},"nodeName":{"type":"string"},"subject":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string"},"sentAt":{"type":["string","null"]},"stats":{"$ref":"#/components/schemas/EmailMetrics"}},"required":["id","kind","campaignId","automationId","nodeKey","name","nodeName","subject","shopId","status","sentAt","stats"]},"EmailStatsPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EmailStatsItem"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"totals":{"$ref":"#/components/schemas/EmailMetrics"}},"required":["items","total","page","pageSize"],"description":"A page of the statistics grid; totals = every e-mail of the asked automations together (query.automationIds)."},"EmailStatsReport":{"type":"object","properties":{"kind":{"type":"string","enum":["campaign","automation"]},"campaignId":{"type":["string","null"]},"automationId":{"type":["string","null"]},"nodeKey":{"type":["string","null"]},"name":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"shopId":{"type":"string"},"nodes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"]}},"filters":{"type":"object","properties":{"engagement":{"type":"array","items":{"type":"string"}},"humans":{"type":"boolean"},"vat":{"type":"boolean"}},"required":["engagement","humans","vat"]},"firstSentAt":{"type":["string","null"]},"lastSentAt":{"type":["string","null"]},"totals":{"$ref":"#/components/schemas/ReportMetrics"},"baseline":{"anyOf":[{"$ref":"#/components/schemas/ReportBaseline"},{"type":"null"}]},"days":{"type":"array","items":{"$ref":"#/components/schemas/ReportDay"}},"domains":{"type":"object","properties":{"sent":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"opened":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"clicked":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"unsubscribed":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"bounced":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"buyers":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}}},"required":["sent","opened","clicked","unsubscribed","bounced","buyers"]},"clients":{"type":"object","properties":{"opened":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"clicked":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}}},"required":["opened","clicked"]},"systems":{"type":"object","properties":{"opened":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}},"clicked":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"}}},"required":["opened","clicked"]},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"},"share":{"type":"number"}},"required":["url","clicks","uniqueClicks","share"]}},"unsubscribeReasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["other","custom","none","redirect","too_often","not_relevant","annoying","not_signed_up","spam_report","misc"]},"count":{"type":"number"}},"required":["reason","count"]}},"bounceReasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["other","suppressed","mailbox_full","delayed","spam_filter","marked_spam","no_address","relay_error","transfer_error","confirmation_timeout","flooded_mailbox","spam_rate_limit","temporary","server_error","mx_error","greylisted"]},"count":{"type":"number"}},"required":["reason","count"]}},"bounceSplit":{"type":"object","properties":{"hard":{"type":"number"},"soft":{"type":"number"}},"required":["hard","soft"]},"revenue":{"type":"array","items":{"$ref":"#/components/schemas/ReportRevenue"}},"revenueDays":{"type":"array","items":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"orders":{"type":"number"},"directOrders":{"type":"number"},"assistedOrders":{"type":"number"},"total":{"type":"string"},"direct":{"type":"string"},"assisted":{"type":"string"}},"required":["date","orders","directOrders","assistedOrders","total","direct","assisted"]}}},"required":["currency","days"]}},"conversionLinks":{"type":"array","items":{"$ref":"#/components/schemas/NamedCount"},"description":"Orders per clicked link (SE \"Nejúspěšnější odkazy\")."},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"'' = the rest (SE \"Ostatní\")."},"count":{"type":"number"},"image":{"type":"string"}},"required":["name","count","image"]},"description":"Items sold (quantity) with a picture."},"engagementSpend":{"type":"array","items":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"grades":{"type":"array","items":{"type":"object","properties":{"grade":{"type":"string"},"orders":{"type":"number"},"total":{"type":"string"}},"required":["grade","orders","total"]}}},"required":["currency","grades"]}},"topSpenders":{"type":"array","items":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"items":{"type":"array","items":{"type":"object","properties":{"contactId":{"type":["string","null"]},"email":{"type":"string"},"orders":{"type":"number"},"total":{"type":"string"}},"required":["contactId","email","orders","total"]}}},"required":["currency","items"]}}},"required":["kind","campaignId","automationId","nodeKey","name","status","startedAt","completedAt","shopId","nodes","filters","firstSentAt","lastSentAt","totals","baseline","days","domains","clients","systems","links","unsubscribeReasons","bounceReasons","bounceSplit","revenue","revenueDays","conversionLinks","products","engagementSpend","topSpenders"]},"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}}}]},"NamedCount":{"type":"object","properties":{"name":{"type":"string","description":"'' = the rest (SE \"Ostatní\")."},"count":{"type":"number"}},"required":["name","count"]},"ReportBaseline":{"type":"object","properties":{"sent":{"type":["number","null"]},"openRate":{"type":"number"},"ctr":{"type":"number"},"ctor":{"type":"number"},"complaintRate":{"type":"number"},"unsubscribeRate":{"type":"number"},"bounceRate":{"type":"number"},"deliveryRate":{"type":"number"},"orderRate":{"type":"number"}},"required":["sent","openRate","ctr","ctor","complaintRate","unsubscribeRate","bounceRate","deliveryRate","orderRate"],"description":"The account's e-mails of the 30 days before (trend \"oproti předchozím 30 dnům\"); sent = average one-time campaign."},"ReportDay":{"type":"object","properties":{"date":{"type":"string"},"opens":{"type":"number"},"clicks":{"type":"number"},"unsubscribed":{"type":"number"},"bounced":{"type":"number"}},"required":["date","opens","clicks","unsubscribed","bounced"]},"ReportMetrics":{"type":"object","properties":{"orders":{"type":"number"},"orderRate":{"type":"number"},"reopeners":{"type":"number","description":"E-mails opened more than once, and their share of the opened ones (SE \"Opakovaná otevření\")."},"reopenRate":{"type":"number"},"webVersionViews":{"type":"number","description":"SE's Online verze and Tisk (ST-04): views of the web version and prints, the e-mails with one, and their share\nof the opened e-mails."},"webVersionUnique":{"type":"number"},"webVersionRate":{"type":"number"},"printViews":{"type":"number"},"printUnique":{"type":"number"},"printRate":{"type":"number"},"sent":{"type":"number"},"delivered":{"type":"number","description":"sent - undelivered"},"undelivered":{"type":"number","description":"Hard or soft bounce (SE \"Nedoručeno\")."},"bounced":{"type":"number"},"softBounced":{"type":"number"},"opens":{"type":"number"},"uniqueOpens":{"type":"number"},"repeatedOpens":{"type":"number"},"machineOpens":{"type":"number","description":"E-mails whose pixel only a machine fetched (Apple Mail Privacy Protection, security gateways): whether a person\nread them is unknown, so they are in no open count or rate."},"clicks":{"type":"number"},"uniqueClicks":{"type":"number"},"unsubscribed":{"type":"number"},"complained":{"type":"number"},"queued":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"openRate":{"type":"number"},"ctr":{"type":"number"},"ctor":{"type":"number"},"unsubscribeRate":{"type":"number"},"bounceRate":{"type":"number"},"complaintRate":{"type":"number"},"deliveryRate":{"type":"number","description":"delivered / sent"}},"required":["orders","orderRate","reopeners","reopenRate","webVersionViews","webVersionUnique","webVersionRate","printViews","printUnique","printRate","sent","delivered","undelivered","bounced","softBounced","opens","uniqueOpens","repeatedOpens","machineOpens","clicks","uniqueClicks","unsubscribed","complained","queued","failed","skipped","openRate","ctr","ctor","unsubscribeRate","bounceRate","complaintRate","deliveryRate"],"description":"Rates as SE computes them: openRate, unsubscribeRate and complaintRate over delivered, ctr and orderRate over sent."},"ReportRevenue":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"orders":{"type":"number"},"directOrders":{"type":"number"},"assistedOrders":{"type":"number"},"total":{"type":"string"},"direct":{"type":"string"},"assisted":{"type":"string"},"averageOrder":{"type":"string"},"directAverage":{"type":"string"},"assistedAverage":{"type":"string"},"eshopOrders":{"type":"number"},"eshopTotal":{"type":"string"},"share":{"type":"number"},"margin":{"type":["string","null"],"description":"SE's Marže and Průměrná marže without VAT (ST-03): from the purchase prices the e-shop sent with the order lines;\nnull when no order of the group has one. *MarginOrders = orders with a known margin."},"marginAverage":{"type":["string","null"]},"marginOrders":{"type":"number"},"directMargin":{"type":["string","null"]},"directMarginAverage":{"type":["string","null"]},"directMarginOrders":{"type":"number"},"assistedMargin":{"type":["string","null"]},"assistedMarginAverage":{"type":["string","null"]},"assistedMarginOrders":{"type":"number"}},"required":["currency","orders","directOrders","assistedOrders","total","direct","assisted","averageOrder","directAverage","assistedAverage","eshopOrders","eshopTotal","share"]},"StatsActivity":{"type":"object","properties":{"sendId":{"type":"string"},"contactId":{"type":["string","null"]},"email":{"type":"string"},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"opens":{"type":"number"},"clicks":{"type":"number"},"type":{"$ref":"#/components/schemas/StatsActivityType"},"source":{"type":"string"},"links":{"type":"array","items":{"type":"string"}},"detail":{"type":"string"}},"required":["sendId","contactId","email","firstAt","lastAt","opens","clicks","type","source","links","detail"]},"StatsActivityType":{"type":"string","enum":["complaint","unsubscribe","open","click","hard","soft"]},"StatsDay":{"type":"object","properties":{"date":{"type":"string"},"opens":{"type":"number"},"clicks":{"type":"number"},"unsubscribed":{"type":"number"}},"required":["date","opens","clicks","unsubscribed"]}}}}