# Poštárna > Poštárna je česká platforma na e-mailový marketing: hromadné rozosielky, automatizácie a štatistiky, ktoré ukážu, čo každý e-mail zarobil. Pre firmy aj e-shopy v Česku a na Slovensku, aplikácia aj podpora po slovensky a po česky. Prevádzkovateľ deriverge s.r.o., IČO 19456361. - Magic Editor: Bloky pretiahnete myšou, na telefóne ich vložíte ťuknutím. Editor ukladá sám. - Automatizácie: Scenár poskladáte na plátne a pred spustením ho vyskúšate nanečisto. Nič sa pritom neodošle. - Uvidíte, čo každý e-mail zarobil. Doručenia, otvorenia, kliky aj objednávky pri každej kampani a každom e-maile automatizácie. - Pre e-shopy: Produkty z feedu, Opustený košík, Objednávky v štatistikách, Kúpte si znova, SK a CZ v jednej kampani. - Prechod zo SmartEmailingu: Stačí API kľúč. Poštárna zo SmartEmailingu iba číta a nič v ňom nemení. - Cenník: Platíte podľa počtu kontaktov. Bez záväzkov, mesačne alebo ročne. Ceny sú bez DPH. Automatizácie, feedy, kupóny, formuláre, landing pages, štatistiky aj podpora v každom tarife. Aktuálny cenník (JSON): https://www.postarna.sk/api/v1/public/price-list - API: API v1 (`/api/v1/tenants/{tenant}/...`) je úplné API, ktoré používa aj webová aplikácia; API v3 (`/api/v3/...`) je kompatibilné so SmartEmailingom; server MCP (`/mcp`) slúži AI asistentom. Prihlásenie API kľúčom: `Authorization: Bearer pst_...`. - Celý strojovo čitateľný popis API: https://www.postarna.cz/api/openapi.json (OpenAPI 3.1). Len jedna skupina: `?tag=Automations` (názvy skupín v poli `tags`). - Pred odoslaním skutočným príjemcom (schválenie kampane, zapnutie automatizácie) vždy najprv spočítajte príjemcov a overte nastavenie: kampaň `POST /campaigns/audience`, automatizácia `POST /automations/validate` a `POST /automations/{id}/test`. ## Produkt - [Poštárna](https://www.postarna.sk/): Hromadné rozosielky, automatizácie a podrobné štatistiky pre firmy všetkých veľkostí. Magic Editor, segmenty, unikátne zľavové kódy, meniny a narodeniny, napojenie na e-shop aj prechod zo SmartEmailingu. Po slovensky a po česky. - [Funkcie](https://www.postarna.sk/#features): Napíšte e-mail, ktorý vyzerá skvele. Pošlite ho presne tým, koho sa týka. A uvidíte, čo vám zarobil. - [Automatizácie](https://www.postarna.sk/#automation): Scenár poskladáte na plátne a pred spustením ho vyskúšate nanečisto. Nič sa pritom neodošle. - [Prechod zo SmartEmailingu](https://www.postarna.sk/#switch): Stačí API kľúč. Poštárna zo SmartEmailingu iba číta a nič v ňom nemení. - [Cenník](https://www.postarna.sk/#pricing): Platíte podľa počtu kontaktov. Bez záväzkov, mesačne alebo ročne. Ceny sú bez DPH. - [Aktuálny cenník (JSON)](https://www.postarna.sk/api/v1/public/price-list): tarify podľa počtu kontaktov s mesačnou cenou bez DPH, ročná zľava, skúšobná doba a limity bezplatného tarifu, priamo z cenníka aplikácie - [Časté otázky](https://www.postarna.sk/#faq): odpovede na otázky: Kto Poštárnu prevádzkuje? Hodí sa Poštárna pre moju firmu? Z akej adresy sa e-maily odosielajú? Ako prejdem zo SmartEmailingu? Ako Poštárna nakladá s osobnými údajmi? Kde nájdem pomoc? ## Návody a zdroje - [Cenník Poštárne](https://www.postarna.sk/cennik): Aktuálny cenník Poštárne: tarify podľa počtu kontaktov, mesačná cena bez DPH, ročná zľava a skúšobná doba. Všetky funkcie v každom tarife. - [Návody na e-mailový marketing](https://www.postarna.sk/navody): Praktické návody krok za krokom: prvý newsletter, opustený košík, e-maily k meninám, win-back, formulár s double opt-in, prechod zo SmartEmailingu, SPF, DKIM a DMARC a segmentácia zákazníkov. - [Ako poslať prvý newsletter](https://www.postarna.sk/navody/prvy-newsletter): Od overenia domény cez import kontaktov a šablónu v editore po testovací e-mail a odoslanie kampane. Prvý newsletter v Poštárni krok za krokom. - [Opustený košík krok za krokom](https://www.postarna.sk/navody/opusteny-kosik): Ako napojiť e-shop postavený na Shoptete jedným riadkom v pätičke a poslať zákazníkovi pripomenutie košíka dve hodiny po poslednej zmene, len keď neobjednal. - [E-maily k meninám a narodeninám](https://www.postarna.sk/navody/meniny-a-narodeniny): Automatické blahoželanie k meninám alebo narodeninám s osobným oslovením a jednorazovým zľavovým kódom. Slovenský aj český kalendár mien. - [Win-back kampaň pre neaktívnych zákazníkov](https://www.postarna.sk/navody/win-back): Ako automaticky osloviť zákazníkov, ktorí dlho nenakúpili: pripomenutie, druhý e-mail s výhodou a koniec série pre tých, ktorí medzitým nakúpia. - [Formulár s potvrdením odberu (double opt-in)](https://www.postarna.sk/navody/formular-double-opt-in): Prihlasovací formulár na web alebo ako pop-up, s potvrdením odberu e-mailom a doloženým súhlasom podľa GDPR. Postup v Poštárni. - [Prechod zo SmartEmailingu do Poštárne](https://www.postarna.sk/navody/prechod-zo-smartemailingu): Ako sami preniesť kontakty, zoznamy, odhlásenia, súhlasy, šablóny a automatizácie zo SmartEmailingu do Poštárne. Stačí API kľúč, v SmartEmailingu sa nič nezmení. - [Lepšia doručiteľnosť so SPF, DKIM a DMARC](https://www.postarna.sk/navody/spf-dkim-dmarc): Prečo e-maily padajú do spamu a ako to opraviť: overenie domény cez DKIM, záznam SPF a DMARC, postupné zvyšovanie objemu a čistá databáza. Návod pre Poštárnu. - [Segmentácia zákazníkov v e-mailingu](https://www.postarna.sk/navody/segmentacia-zakaznikov): Ako rozdeliť kontakty podľa nákupov, aktivity a súhlasov a posielať každej skupine to, čo ju zaujíma. Príklady segmentov pre e-shopy a postup v Poštárni. - [Slovník pojmov e-mailového marketingu](https://www.postarna.sk/slovnik): Čo znamená double opt-in, miera otvorenia, CTR, soft a hard bounce, SPF, DKIM, DMARC, segment, opustený košík alebo win-back. Krátke definície a ako to rieši Poštárna. - [Integrácie Poštárne](https://www.postarna.sk/integracie): Napojenie Poštárne na Shoptet, produktové feedy Google Merchant, Heureka a Zboží.cz, RSS, import CSV, webhooky, API, API kompatibilné so SmartEmailingom a MCP pre AI asistentov. ## API dokumentácia: Začíname - [API dokumentácia Poštárne](https://www.postarna.sk/docs/api): Čo API Poštárne vie, ako je dokumentácia usporiadaná a kde začať. - [Začíname](https://www.postarna.sk/docs/api/getting-started): API kľúč, ID firmy a prvé volanie API za päť minút. - [Pravidlá API](https://www.postarna.sk/docs/api/conventions): Formáty dát, stránkovanie, triedenie, chyby, limity požiadaviek, opakovanie a súbežné úpravy. ## API dokumentácia: Koncepty - [Firma a e-shopy](https://www.postarna.sk/docs/api/tenants-and-shops): Firma (tenant), jej e-shopy s menou a jazykom, časová zóna a izolácia dát. - [Kontakty a súhlasy](https://www.postarna.sk/docs/api/contacts-and-consent): Kontakt a jeho stavy, súhlasy a účely spracúvania, potlačenie a blacklist, komu Poštárna smie písať. - [Zoznamy a segmenty](https://www.postarna.sk/docs/api/lists-and-segments): Kedy použiť zoznam a kedy segment, stavy členstva, jazyk podmienok segmentov a živý náhľad počtu. - [Šablóny a personalizácia](https://www.postarna.sk/docs/api/templates-and-personalization): Šablóny e-mailov, obsah a verzie, kontrola obsahu, zástupné značky, skripty Twig, kupóny a dáta objednávok. - [Kampane](https://www.postarna.sk/docs/api/campaigns): Životný cyklus kampane, publikum a jeho výpočet, schválenie s počtom príjemcov, plánovanie, pauza a zrušenie. - [Automatizácie](https://www.postarna.sk/docs/api/automations): Model grafu, uzly a výstupy, spúšťače, jazyk podmienok, čakanie, validácia, zapnutie, uloženie bežiaceho scenára, verzie a testovanie. - [Referencia automatizácií](https://www.postarna.sk/docs/api/automation-reference): Presné schémy všetkých uzlov automatizácie, udalostí, podmienok, pravidiel segmentov a časových údajov s overenými príkladmi. - [Objednávky, feedy a kupóny](https://www.postarna.sk/docs/api/orders-feeds-coupons): Zápis objednávok a mapa stavov, produktové, zákaznické a objednávkové feedy, zásobníky zľavových kupónov a konverzie. ## API dokumentácia: Recepty - [Recept: opustený košík](https://www.postarna.sk/docs/api/recipe-abandoned-cart): Automatizácia, ktorá za 2 hodiny pripomenie neodoslaný košík, s udalosťami košíka posielanými z e-shopu. - [Recept: séria po nákupe](https://www.postarna.sk/docs/api/recipe-post-purchase): Poďakovanie a prosba o hodnotenie 3 dni po dokončenej objednávke, tip na prípravu tým, kto nekliknú. - [Recept: meniny so zľavou](https://www.postarna.sk/docs/api/recipe-name-days): Každý deň o 8:00 zablahoželať kontaktom, ktoré majú meniny, a dať im jednorazový zľavový kód. - [Recept: návrat neaktívnych zákazníkov](https://www.postarna.sk/docs/api/recipe-win-back): Zákazníkom 120 dní bez nákupu poslať pripomenutie a po týždni druhé, ak medzitým nenakúpia. - [Recept: prihlasovací formulár s potvrdením](https://www.postarna.sk/docs/api/recipe-double-opt-in): Formulár s double opt-in na web, zoznam odberateľov, súhlas s účelom a uvítací e-mail po potvrdení. - [Recept: import kontaktov z CSV](https://www.postarna.sk/docs/api/recipe-import-contacts): Nahranie CSV, náhľad mapovania a problémov, spustenie importu s doloženým súhlasom a sledovanie priebehu. - [Recept: odoslanie kampane](https://www.postarna.sk/docs/api/recipe-send-campaign): Koncept kampane, obsah, kontrola obsahu, počet príjemcov, testovací e-mail, schválenie s plánovaným časom a zrušenie. - [Recept: príjem webhookov](https://www.postarna.sk/docs/api/recipe-webhook-consumer): Registrácia účtových webhookov, overenie Basic, idempotentné spracovanie a ukázkový príjemca v Pythone a Node.js. ## API dokumentácia: Integrácie - [Webhooky](https://www.postarna.sk/docs/api/webhooks): Účtové webhooky (nový kontakt, odhlásenie, doručenie, otvorenie, klik), tvar dát, doručovanie a opakovanie, zabezpečenie a webhook v automatizácii. - [MCP pre AI asistentov](https://www.postarna.sk/docs/api/mcp): Pripojenie ChatGPT, Claude a ďalších klientov k serveru MCP Poštárne, rozsahy prístupu, nástroje a povinné potvrdenie pred odoslaním. - [Kompatibilita so SmartEmailingom](https://www.postarna.sk/docs/api/smartemailing): API v3 a CSV štatistiky s rovnakými cestami, obálkami a chybami ako SmartEmailing, prihlásenie, limity a rozdiely. ## API dokumentácia: Referencia API - [Prehľad operácií](https://www.postarna.sk/docs/api/reference): Všetky operácie API po skupinách s odkazmi na podrobnú referenciu a strojovo čitateľný dokument OpenAPI. - [Chyby a limity](https://www.postarna.sk/docs/api/errors-and-limits): Každý kód chyby s významom a nápravou, HTTP stavy, limity požiadaviek a limity jednotlivých akcií. - [Contacts](https://www.postarna.sk/docs/api/reference-contacts): Contacts of the company: profile fields, consent state, suppressions, custom fields, purposes of processing (consents), activities and GDPR export and erasure. - [Lists](https://www.postarna.sk/docs/api/reference-lists): Contact lists with explicit membership (manual and form lists) and the lists bound to an e-shop (read only membership). - [Segments](https://www.postarna.sk/docs/api/reference-segments): Rule based groups of contacts of one e-shop: an AND / OR tree of conditions, evaluated live (daily) or as a snapshot (static). - [Campaigns](https://www.postarna.sk/docs/api/reference-campaigns): One-off e-mail campaigns (newsletters): draft, audience, content, test, approve (send now or schedule), pause, resume, cancel, language variants. - [Templates and content](https://www.postarna.sk/docs/api/reference-templates): E-mail templates (HTML or the visual MJML editor), content versions, lint and spam check, footers, unsubscribe pages, saved editor elements, script templates (Twig), SMS templates, landing pages, surveys and the file manager. - [Automations](https://www.postarna.sk/docs/api/reference-automations): Automation scenarios: a graph of triggers, conditions, waits and actions; validation, versions, activation, test and trace, run history, statistics, and the contact events API that feeds event triggers (custom events, carts, page visits). - [Forms](https://www.postarna.sk/docs/api/reference-forms): Sign-up forms (double opt-in): builder settings, embed code, history. - [Imports and exports](https://www.postarna.sk/docs/api/reference-imports-and-exports): CSV import of contacts (upload, preview, run) and CSV exports. - [Orders, feeds and coupons](https://www.postarna.sk/docs/api/reference-orders-and-feeds): Orders of the e-shops (they drive purchase triggers and conditions), order states, product and customer feeds, coupon stacks. - [Statistics](https://www.postarna.sk/docs/api/reference-statistics): E-mail statistics of campaigns and automations, dashboard, conversions. - [Sending and deliverability](https://www.postarna.sk/docs/api/reference-sending): Senders, sending domains (SPF, DKIM, DMARC), DMARC reports, sending mode. - [Account and settings](https://www.postarna.sk/docs/api/reference-account): Shops (e-shops) of the company, company data, consent settings, notifications, labels, web tracking, billing (read), SmartEmailing migration state. - [SmartEmailing compatible API v3](https://www.postarna.sk/docs/api/reference-smartemailing-v3): The same paths, envelopes and errors as SmartEmailing REST API v3 (read operations and account webhooks). HTTP Basic: member e-mail + API key. - [SmartEmailing compatible CSV statistics](https://www.postarna.sk/docs/api/reference-smartemailing-csv): Semicolon separated CSV as SmartEmailing /api/csv: e-mail statistic ids, per-contact event details, list members. - [MCP server for AI assistants](https://www.postarna.sk/docs/api/reference-mcp): Model Context Protocol over Streamable HTTP (JSON-RPC 2.0). Tools map to API v1 routes; sending, deleting and other irreversible actions need a preview and a confirm token. - [OAuth 2.1 for AI assistants](https://www.postarna.sk/docs/api/reference-oauth): Dynamic client registration, authorization code with PKCE, tokens and revocation, server metadata. Used by MCP clients; integrations use API keys instead. - [This document](https://www.postarna.sk/docs/api/reference-meta): The OpenAPI document itself. - [História zmien](https://www.postarna.sk/docs/api/changelog): Zmeny API a dokumentácie. ## OpenAPI - [openapi.json](https://www.postarna.cz/api/openapi.json): OpenAPI 3.1, všetky operácie a schémy ## Optional - [llms-full.txt](https://www.postarna.sk/llms-full.txt): tento prehľad, popis produktu a všetky návody API dokumentácie v jednom súbore Markdown - [Obchodné podmienky služby Poštárna](https://www.postarna.sk/terms): Verzia 1.1, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. - [Reklamačný poriadok a podpora služby Poštárna](https://www.postarna.sk/claims): Verzia 1.0, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. - [Zmluva o spracúvaní osobných údajov](https://www.postarna.sk/dpa): Verzia 1.0, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. - [Zásady používania a pravidlá rozosielania](https://www.postarna.sk/acceptable-use): Verzia 1.0, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. - [Zásady ochrany osobných údajov služby Poštárna](https://www.postarna.sk/privacy): Verzia 1.0, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. - [Zásady používania cookies](https://www.postarna.sk/cookies): Verzia 1.0, účinná od 12. 10. 2026, prevádzkovateľ deriverge s.r.o. --- # Poštárna: Platforma pre e-mailový marketing Hromadné rozosielky, automatizácie a štatistiky, z ktorých hneď spoznáte, čo funguje. Pre každú firmu. Česká aplikácia od deriverge s.r.o., podpora po slovensky aj po česky. ## Magic Editor: Poskladajte e-mail ako stavebnicu Bloky pretiahnete myšou, na telefóne ich vložíte ťuknutím. Editor ukladá sám. - Bloky a sekcie: Text, obrázky, tlačidlá a stĺpce. Obrázky orežete priamo v editore. - Produkty z feedu: Vyberiete produkt a editor doplní obrázok, cenu aj odkaz. - Kód pre každého: Každý príjemca dostane vlastný zľavový kód zo zásobníka. - Telefón aj tmavý režim: Náhľad na telefóne aj v tmavom režime ešte pred odoslaním. - Kontrola pred odoslaním: Testovací e-mail a antispamová kontrola, ktorá každý nález vysvetlí a poradí, ako ho opraviť. ## Uvidíte, čo každý e-mail zarobil Doručenia, otvorenia, kliky aj objednávky pri každej kampani a každom e-maile automatizácie. - Priame aj asistované objednávky: Objednávka do 24 hodín od kliknutia je priama, do 5 dní od kliknutia alebo do 24 hodín od otvorenia asistovaná. - Eurá a koruny zvlášť: Tržby v rôznych menách sa nikdy nesčítavajú. ## Automatizácie, ktoré pracujú aj v noci Scenár poskladáte na plátne a pred spustením ho vyskúšate nanečisto. Nič sa pritom neodošle. Spúšťače scenárov: Hneď teraz, V plánovanom čase, Opakovane, Nový odberateľ, Nová objednávka, Zmena v košíku, Vyplnenie formulára, Klik na odkaz, Meniny, narodeniny, výročie, Kúpte si znova. - Výsledky pri každom e-maile: Odoslané, otvorené aj objednávky krok po kroku. - Stopa jedného kontaktu: Uvidíte, kadiaľ kontakt scenárom prešiel a prečo, aj kadiaľ by išiel nanečisto. - Webhooky a upozornenia: Scenár zavolá webhook alebo upozorní kolegov. ## Máte e-shop? Poštárna vie ešte viac. - Produkty z feedu: Feed Google Merchant, napríklad zo Shoptetu. Obrázok aj cena sa doplnia samy. - Opustený košík: Jeden riadok v pätičke e-shopu a automatizácia vie, čo zostalo v košíku. - Objednávky v štatistikách: Objednávky sa spoja s klikmi v e-mailoch. - Kúpte si znova: Pripomenutie ďalšieho nákupu v pravý čas. - SK a CZ v jednej kampani: Každá verzia s produktmi a cenami svojho e-shopu. ## Všetko, čo e-mailing potrebuje - Segmenty: Prepočítavajú sa samy. - Formuláre a pop-upy: S dvojitým potvrdením. - Landing pages: Vrátane dotazníkov. - Doručiteľnosť: Kontrola SPF, DKIM a DMARC. - Súhlasy a odhlásenia: Odhlásenému už nič nepríde. - Meniny a narodeniny: S oslovením menom. - Po slovensky aj po česky: Aplikácia, podpora aj kalendár mien. - API a webhooky: Aj pre AI asistentov cez MCP. ## Zo SmartEmailingu prejdete sami Stačí API kľúč. Poštárna zo SmartEmailingu iba číta a nič v ňom nemení. 1. Pripojenie: Zadáte e-mail a API kľúč. Ukážeme vám, kde ho nájdete. 2. Čo preniesť: Zoznamy, súhlasy, šablóny a názvy automatizácií ako koncepty. 3. Prenos: Odhlásenia idú prvé, aby nikto nedostal e-mail navyše. 4. Kontrola počtov: Na konci porovnáte počty v oboch systémoch. ## Cenník: Jeden tarif. Všetky funkcie. Platíte podľa počtu kontaktov. Bez záväzkov, mesačne alebo ročne. Ceny sú bez DPH. Automatizácie, feedy, kupóny, formuláre, landing pages, štatistiky aj podpora v každom tarife. Aktuálny cenník (JSON): https://www.postarna.sk/api/v1/public/price-list (tarify podľa počtu kontaktov s mesačnou cenou bez DPH, ročná zľava, skúšobná doba a limity bezplatného tarifu, priamo z cenníka aplikácie). ## Na čo sa nás pýtate ### Kto Poštárnu prevádzkuje? Poštárnu prevádzkuje česká spoločnosť deriverge s.r.o., IČO 19456361. Od nej dostanete faktúru aj podporu. ### Hodí sa Poštárna pre moju firmu? Áno. Poštárnu využije každá firma, ktorá posiela newslettre, oznámenia alebo automatické e-maily svojim zákazníkom a chce vidieť ich výsledky. E-shopom navyše číta produktové feedy vo formáte Google Merchant, spája objednávky s klikmi v e-mailoch a cez webtracking stráži košíky. Jeden účet zvládne viac značiek či e-shopov v eurách aj v korunách. ### Z akej adresy sa e-maily odosielajú? Z vašej vlastnej domény. Doménu zadáte v nastaveniach, záznamy DNS pre ňu pripravíme a sprievodca potom sám skontroluje, či sú v poriadku. Ostré odosielanie nového účtu schvaľujeme, zvyčajne do jedného pracovného dňa. Dovtedy si posielate testovacie e-maily. ### Ako prejdem zo SmartEmailingu? V nastaveniach zadáte API kľúč svojho účtu v SmartEmailingu a vyberiete, čo preniesť. Poštárna prenesie kontakty, zoznamy, odhlásenia, súhlasy, šablóny a názvy automatizácií ako koncepty a na konci porovná počty. Zo SmartEmailingu iba číta. ### Ako Poštárna nakladá s osobnými údajmi? Údaje vašich kontaktov spracúvame ako sprostredkovateľ podľa zmluvy o spracúvaní osobných údajov. Evidujeme účely a súhlasy a odhlásenému kontaktu už nič nepošleme. ### Kde nájdem pomoc? Napíšte na podpora@postarna.sk alebo zavolajte na +420 777 849 095. Odpovedáme po slovensky aj po česky. --- # Návody na e-mailový marketing Postupy pre marketérov a majiteľov e-shopov, ktorí chcú posielať e-maily, ktoré sa čítajú a zarábajú. Každý návod vysvetlí, prečo to robiť, a potom krok za krokom ukáže, ako to nastaviť v Poštárni. Neznáme pojmy nájdete v [slovníku](https://www.postarna.sk/slovnik), napojenie na e-shop a ďalšie systémy v prehľade [integrácií](https://www.postarna.sk/integracie). Vývojári nájdu rovnaké postupy cez API ako [recepty v API dokumentácii](https://www.postarna.sk/docs/api#ako-je-dokumentacia-usporiadana). --- # Ako poslať prvý newsletter Newsletter je najjednoduchší spôsob, ako pravidelne pripomínať značku a privádzať zákazníkov späť. Aby dorazil do doručenej pošty a nie do spamu, potrebuje tri veci: overenú doménu odosielateľa, kontakty so súhlasom a e-mail, ktorý sa dobre zobrazí na telefóne aj v počítači. ## Skôr ako začnete • **Doména:** e-maily odchádzajú z vašej domény (napríklad novinky@vasafirma.sk), nie z Gmailu ani Azetu. Budete potrebovať prístup k nastaveniu DNS. • **Kontakty so súhlasom:** posielajte len ľuďom, ktorí sa na odber prihlásili, alebo zákazníkom v rámci [zákazníckej výnimky](https://www.postarna.sk/slovnik#soft-opt-in-zakaznicka-vynimka). • **Ostré odosielanie:** nový účet posiela najprv len testovacie e-maily na testovacie adresy firmy. Ostré odosielanie zapne prevádzkovateľ Poštárne po schválení účtu. ## Postup krok za krokom {#postup} 1. **Overte doménu**: v Nastaveniach › Odosielanie › DNS záznamy cez Nová doména prejdete štyri kroky (Doména, Záznamy v DNS, Kontrola, Adresy odosielateľa). Podrobne v návode [SPF, DKIM a DMARC](https://www.postarna.sk/navody/spf-dkim-dmarc). 2. **Nahrajte kontakty**: v Kontakty a zoznamy › Importy nahráte súbor CSV alebo export zo Shoptetu, priradíte stĺpce a vyberiete zoznam. Neplatné adresy import preskočí a odhlásené adresy zostanú odhlásené. 3. **Pripravte e-mail**: v Obsah a vzhľad › Šablóny e-mailov založíte šablónu a v Magic Editore ju poskladáte z blokov (text, obrázky, tlačidlá, produkty z feedu). Náhľad ukáže e-mail na telefóne aj v tmavom režime. 4. **Pošlite si test**: tlačidlo Testovací e-mail pošle náhľad na testovacie adresy firmy (nastavíte ich v Nastaveniach › Odosielanie). Antispamová kontrola vysvetlí každý nález a poradí, ako ho opraviť. 5. **Založte kampaň**: v Kampane › E-mailové kampane spustíte sprievodcu. Vyplníte názov, e-shop, odosielateľa, predmet a [preheader](https://www.postarna.sk/slovnik#preheader), vyberiete zoznam alebo segment a sprievodca hneď spočíta príjemcov aj vynechané kontakty. 6. **Odošlite alebo naplánujte**: zvolíte Ihneď, Naplánovať (dátum a čas) alebo Vyriešiť neskôr (kampaň zostane konceptom). Odoslanie potvrdíte s počtom príjemcov a časom. 7. **Sledujte výsledky**: v štatistikách kampane uvidíte doručenie, otvorenia, prekliky, odhlásenia a objednávky po prekliku zvlášť v eurách a v korunách. ## Tipy na lepšie výsledky • Predmet píšte krátko a konkrétne, preheader ho má dopĺňať, nie opakovať. • Neaktívne kontakty (angažovanosť E) sprievodca kampaňou v predvolenom nastavení vynechá. Zlepšuje to doručiteľnosť. • Oslovujte menom. Na Slovensku sa oslovuje v 1. páde (Dobrý deň, Peter), takže stačí meno kontaktu bez skloňovania. • Posielajte pravidelne a v rovnakom rytme, nech odberatelia vedia, čo čakať. Čo znamenajú čísla v štatistikách, vysvetľuje [slovník](https://www.postarna.sk/slovnik#miera-otvorenia-open-rate). Postup cez API je v recepte [Odoslanie kampane](https://www.postarna.sk/docs/api/recipe-send-campaign). --- # Opustený košík krok za krokom Zákazník vloží tovar do košíka, odbehne a objednávku nedokončí. Pripomenutie košíka je jeden z automatických e-mailov, ktoré sa e-shopom oplatia najviac: príde vo chvíli, keď zákazník o nákupe ešte premýšľa, a vedie ho rovno späť. ## Ako to v Poštárni funguje • **Webtracking**: jeden riadok v pätičke e-shopu posiela do Poštárne košík návštevníka, ktorého e-shop pozná: prihláseného zákazníka alebo toho, kto v pokladni zadal e-mail. Skript nepoužíva cookies ani odtlačok prehliadača a keď má e-shop lištu cookies, posiela košík až potom, ako návštevník prijme personalizačné cookies. • Košík sa uloží len pri adrese, ktorá už je kontaktom e-shopu, a len kým v e-shope beží scenár so spúšťačom Každá zmena v košíku. • Každá zmena košíka je udalosť. Keď zákazník košík zmení znova, čakanie začne od začiatku, takže pripomenutie príde jedno, až po poslednej zmene. ## Postup krok za krokom {#postup} 1. **Zapnite webtracking**: v Nastaveniach › Dátové zdroje › Webtracking skontrolujte, že je zapnuté Používať, a skopírujte kód pre váš e-shop. 2. **Vložte kód do pätičky e-shopu**: v administrácii Shoptetu otvorte Vzhľad a obsah › Editor › HTML kód › Päta, vložte riadok a uložte. 3. **Pripravte e-mail**: v Obsah a vzhľad › Šablóny e-mailov vytvorte šablónu pripomenutia s tlačidlom späť do košíka. Krátky text a jedna jasná výzva fungujú najlepšie. 4. **Založte automatizáciu**: v Automatizácie › Nová automatizácia zadajte názov, vyberte e-shop a otvorte plátno. 5. **Nastavte spúšťač**: uzol Pri udalosti s udalosťou Každá zmena v košíku a opakovaným vstupom Reštartovať s každou ďalšou udalosťou. 6. **Počkajte a overte košík**: za spúšťač dajte Čakanie (napríklad 2 hodiny) a Podmienku: Počet položiek v nákupnom košíku je väčší ako 0 a Objednávka od vstupu do scenára nenastala. 7. **Odošlite e-mail**: do vetvy áno dajte uzol Odoslať e-mail so šablónou pripomenutia. Vetva nie scenár ukončí. 8. **Otestujte a zapnite**: scenár otestujte bez odoslania, zapnite ho a na e-shope sa prihláste testovacím zákazníckym účtom. Po vložení tovaru do košíka ho uvidíte v prehľade Webtracking. ## Tipy • Nečakajte príliš dlho, ale ani len pár minút: zákazník môže byť práve v pokladni. Dve hodiny sú rozumný začiatok. • Druhé pripomenutie pridáte ďalším Čakaním a Podmienkou. Zľavu dávajte opatrne a radšej [jednorazovým kódom](https://www.postarna.sk/slovnik#unikatny-zlavovy-kod). • Koľko objednávok scenár priviedol, uvidíte v štatistikách automatizácie ako [konverzie](https://www.postarna.sk/slovnik#konverzia-z-e-mailu). Vývojári môžu košíky posielať aj cez API, pozri recept [Opustený košík](https://www.postarna.sk/docs/api/recipe-abandoned-cart). --- # E-maily k meninám a narodeninám Blahoželanie k meninám je na Slovensku aj v Česku zvyk, ktorý zákazníci poznajú a majú radi. Automatický e-mail s osobným oslovením a malým darčekom pripomenie značku bez pocitu reklamy a často vedie k nákupu. ## Ako Poštárna spozná meniny • Keď má kontakt vyplnené pole Meniny, oslavuje v ten deň. • Inak sa meniny hľadajú podľa krstného mena v kalendári jazyka kontaktu: slovenský pre slovenské kontakty, inak český. Kontakt bez mena meniny nemá. • Narodeniny sa berú z poľa Narodeniny pri kontakte. ## Postup krok za krokom {#postup} 1. **Nahrajte zľavové kódy**: v Nastaveniach › Dátové zdroje › Zľavové kupóny založte zásobník a vložte jednorazové kódy vytvorené v e-shope, jeden na riadok. 2. **Napíšte blahoželanie**: v Obsah a vzhľad › Šablóny e-mailov vytvorte šablónu. Oslovte menom kontaktu a kód vložte v Magic Editore prvkom Kupón (lišta Nový prvok), v ktorom vyberiete zásobník, text nad kódom a tlačidlo. V HTML editore vložíte kód značkou kupónu (skupina Zľavové kupóny v ponuke značiek). Každý príjemca dostane vlastný kód. 3. **Založte automatizáciu**: v Automatizácie › Nová automatizácia zadajte názov a e-shop. 4. **Nastavte spúšťač**: uzol Meniny, narodeniny, výročie s voľbou Dnes má meniny (alebo Dnes má narodeniny) a časom odoslania, napríklad 8:00. 5. **Pridajte e-mail**: za spúšťač dajte uzol Odoslať e-mail so šablónou blahoželania. 6. **Otestujte a zapnite**: scenár otestujte bez odoslania a zapnite. Poštárna potom každý deň prejde kontakty, ktoré oslavujú, a pošle im blahoželanie. ## Tipy • Strážte, koľko kódov v zásobníku zostáva. Keď kódy dôjdu, e-mail s kódom neodíde. • Blahoželanie píšte krátko a osobne, zľava má byť darček, nie hlavná správa. • Pri českých kontaktoch vloží značka `{{df_salution}}` oslovenie v 5. páde (Petře, Lucie), slovenské mená nechá v 1. páde. • Spúšťač vie aj výročie prvého nákupu alebo dátum z vlastného poľa, napríklad koniec predplatného. Postup cez API: recept [Meniny so zľavou](https://www.postarna.sk/docs/api/recipe-name-days). Pojmy: [oslovenie v 5. páde](https://www.postarna.sk/slovnik#oslovenie-v-5-pade), [unikátny zľavový kód](https://www.postarna.sk/slovnik#unikatny-zlavovy-kod). --- # Win-back kampaň pre neaktívnych zákazníkov Získať nového zákazníka stojí viac ako priviesť späť toho, kto už raz nakúpil. Win-back séria osloví zákazníkov, ktorí dlho nenakúpili: najprv im pripomenie značku, a keď nereagujú, ponúkne dôvod vrátiť sa. ## Kedy je zákazník neaktívny Závisí to od sortimentu. Pri tovare, ktorý sa kupuje pravidelne (káva, kozmetika, krmivo), môže byť neaktívny zákazník už po dvoch alebo troch mesiacoch, pri drahšom tovare po roku. Začnite s hranicou, ktorá zodpovedá bežnému odstupu medzi nákupmi vo vašom e-shope, napríklad 120 dní. ## Postup krok za krokom {#postup} 1. **Pripravte dva e-maily**: v Obsah a vzhľad › Šablóny e-mailov vytvorte pripomenutie (novinky, obľúbené produkty) a druhý e-mail s výhodou, ideálne s [jednorazovým zľavovým kódom](https://www.postarna.sk/slovnik#unikatny-zlavovy-kod). 2. **Založte automatizáciu**: v Automatizácie › Nová automatizácia zadajte názov a e-shop. 3. **Nastavte spúšťač**: uzol Opakovať, ktorý každý deň prejde kontakty e-shopu. Vo filtri zvoľte pravidlo Posledná objednávka staršia ako 120 dní a opakovaný vstup Len raz navždy, aby každý zákazník prešiel sériou len raz. 4. **Pošlite prvý e-mail**: za spúšťač dajte Odoslať e-mail s pripomenutím a potom Čakanie 7 dní. 5. **Rozdeľte podľa nákupu**: pridajte Podmienku Objednávka od vstupu do scenára. Kto nakúpil, scenár končí; ostatným pošlite druhý e-mail s výhodou. 6. **Pridajte cieľ**: uzol Cieľ scenára s objednávkou zaistí, že kto nakúpi kedykoľvek počas série, scenár hneď opustí. 7. **Otestujte a zapnite**: scenár otestujte bez odoslania a zapnite. Výsledky sledujte v štatistikách automatizácie. ## Tipy • Win-back funguje aj pre odberateľov, ktorí nenakupujú, ale prestali otvárať: použite pravidlo podľa [angažovanosti](https://www.postarna.sk/slovnik#angazovanost-kontaktu). • Kto nereaguje ani na druhý e-mail, tomu posielajte menej. Neaktívne kontakty zhoršujú [doručiteľnosť](https://www.postarna.sk/slovnik#dorucitelnost). • Podobný, ale jemnejší je spúšťač Kúpte si znova: pripomenie ďalší nákup podľa toho, ako často zákazník zvyčajne nakupuje. Postup cez API: recept [Návrat neaktívnych zákazníkov](https://www.postarna.sk/docs/api/recipe-win-back). --- # Formulár s potvrdením odberu (double opt-in) Prihlasovací formulár je hlavný zdroj nových odberateľov. S potvrdením odberu ([double opt-in](https://www.postarna.sk/slovnik#double-opt-in)) sa do databázy nedostanú preklepy, cudzie ani falošné adresy a o každom odberateľovi máte záznam, kedy a s akým textom súhlasil. ## Čo sa stane po odoslaní formulára 1. Kontakt čaká na potvrdenie a k prihláške sa uloží IP adresa, prehliadač, stránka a presné znenie súhlasu. 2. Odíde potvrdzovací e-mail bez reklamy. Odkaz v ňom platí 7 dní a na jednu adresu odídu najviac 3 potvrdenia za deň. 3. Po kliknutí je kontakt prihlásený, zaradí sa do zoznamov formulára a zapíše sa súhlas s účelom spracúvania. Formulár odpovedá vždy rovnako, takže neprezradí, kto už v databáze je. Odhlásený kontakt sa tak môže znova prihlásiť, nedoručiteľná adresa alebo adresa so sťažnosťou nedostane nič. ## Postup krok za krokom {#postup} 1. **Pripravte zoznam**: v Kontakty a zoznamy › Zoznamy kontaktov založte zoznam pre odberateľov, napríklad Newsletter. 2. **Skontrolujte účel spracúvania**: v Kontakty a zoznamy › Účely spracúvania os. údajov je účel, ku ktorému sa súhlas zapíše, napríklad zasielanie obchodných oznámení. 3. **Vytvorte formulár**: v Obsah a vzhľad › Webové formuláre založte formulár, vyberte zoznam, účel a text súhlasu a pridajte polia (napríklad meno). 4. **Nastavte potvrdenie**: potvrdenie odberu je zapnuté v predvolenom nastavení. Môžete upraviť potvrdzovací e-mail a stránky po odoslaní a po potvrdení. 5. **Vložte formulár na web**: skopírujte kód formulára do stránky alebo ho zobrazte ako pop-up či vysúvacie okno. Pri pop-upe nastavíte, kedy sa ukáže (po načítaní, po čase, po posunutí stránky) a ako často. 6. **Privítajte nových odberateľov**: v automatizácii so spúšťačom Pri udalosti a udalosťou Nový odberateľ pošlite uvítací e-mail. ## Tipy • Na telefóne sa pop-up ukáže, len keď to zapnete, a to ako spodný panel s veľkým tlačidlom na zatvorenie, nie cez celú obrazovku. • Pop-up sa dá skryť prihláseným zákazníkom e-shopu na Shoptete a tým, ktorí prišli z vášho e-mailu, ak odkazy v e-mailoch nesú parameter Poštárne. • Sľubujte len to, čo budete posielať, a ako často. Odberateľ, ktorý vie, čo čakať, sa menej odhlasuje. Postup cez API: recept [Formulár s potvrdením](https://www.postarna.sk/docs/api/recipe-double-opt-in). --- # Prechod zo SmartEmailingu do Poštárne Prechod zvládnete sami za pár minút. Poštárna sa k SmartEmailingu pripojí vaším API kľúčom, dáta len číta a nič v ňom nemení. Najprv prenesie odhlásenia a blacklist, aby nikto nedostal e-mail navyše, a na konci porovná počty v oboch systémoch. ## Čo sa prenesie • **Vždy**: kontakty so všetkými vlastnými poľami, zoznamy a členstvá, odhlásenia, blacklist a nedoručiteľné adresy. • **Podľa voľby**: účely spracúvania a súhlasy kontaktov s dátumom platnosti, e-maily z knižnice ako šablóny (obrázky sa prenesú do správcu súborov) a automatizácie ako koncepty. SmartEmailing odovzdá len názvy automatizácií, kroky doplníte v editore a samy sa nespustia. • Kontakt, ktorý už v Poštárni máte, sa nezdvojí: údaje sa zlúčia a ručné úpravy zostanú. ## Postup krok za krokom {#postup} 1. **Vytvorte API kľúč v SmartEmailingu**: v Nastaveniach › Dátové zdroje › API kľúče kliknite na Vytvoriť nový kľúč a kľúč hneď skopírujte, SmartEmailing ho ukáže len raz. 2. **Pripojte SmartEmailing**: v Poštárni otvorte Nastavenia › Dátové zdroje › Prechod zo SmartEmailingu (spúšťa ho Správca účtu), vložte prihlasovací e-mail do SmartEmailingu a kľúč a kliknite na Overiť a pripojiť. 3. **Vyberte, čo preniesť**: pri každom zozname zvoľte, čo znamená: prihlásení na odber (súhlas), zákazníci bez potvrdeného súhlasu, odhlásení (nikdy neposielať) alebo nepreniesť. Návrh je pripravený podľa názvu zoznamu, skontrolujte ho. 4. **Spustite prenos**: prenos beží na pozadí, stránku môžete zavrieť. Keď sa preruší, spustíte ho znova a nadviaže tam, kde skončil. 5. **Skontrolujte počty**: tabuľka porovná kontakty, blacklist, nedoručiteľné adresy, odhlásenia, polia, súhlasy, šablóny a automatizácie v oboch systémoch. Posielať z Poštárne je bezpečné, až keď sú v nej všetky odhlásenia. 6. **Zapnite súbeh, ak ho potrebujete**: kým ešte posielate aj zo SmartEmailingu, môže Poštárna každú hodinu načítať nové kontakty, odhlásenia a blacklist. Keď SmartEmailing prestanete používať, synchronizáciu vypnite. ## Integrácie a API Vlastné napojenie postavené na REST API v3 SmartEmailingu funguje s Poštárňou po zmene adresy, používateľského mena a kľúča: Poštárna má API v3 s rovnakými cestami, obálkami a chybami na čítanie kontaktov, zoznamov a polí, webhooky a vybrané CSV štatistiky. Kontakty a zoznamy cez API v3 zatiaľ nezapisujete, na to slúži API v1. Podrobnosti a rozdiely sú v [API dokumentácii](https://www.postarna.sk/docs/api/smartemailing). ## Po prechode • Overte doménu odosielateľa v Nastaveniach › Odosielanie, pozri [SPF, DKIM a DMARC](https://www.postarna.sk/navody/spf-dkim-dmarc). • Doplňte kroky automatizácií prenesených ako koncepty a pred zapnutím ich otestujte. • Nahraďte kód formulárov a webtrackingu na webe kódmi z Poštárne. --- # Lepšia doručiteľnosť so SPF, DKIM a DMARC Gmail, Outlook, Seznam aj ďalšie poštové služby dnes od hromadných odosielateľov vyžadujú overenú doménu. E-mail bez podpisu DKIM a bez záznamov SPF a DMARC častejšie skončí v spame alebo ho služba odmietne. Nastavenie zaberie pár minút a robí sa raz. ## Tri záznamy v DNS • **[DKIM](https://www.postarna.sk/slovnik#dkim)** podpisuje každý e-mail. Poštová služba podľa verejného kľúča vo vašej doméne overí, že e-mail prišiel od vás. • **[SPF](https://www.postarna.sk/slovnik#spf)** vymenuje servery, ktoré smú za doménu odosielať. • **[DMARC](https://www.postarna.sk/slovnik#dmarc)** hovorí, čo robiť s e-mailom, ktorý kontrolou neprejde, a kam posielať súhrnné správy. ## Postup krok za krokom {#postup} 1. **Zadajte doménu**: v Nastaveniach › Odosielanie › DNS záznamy kliknite na Nová doména a zadajte doménu, z ktorej chcete posielať, napríklad vasafirma.sk. Domény bezplatných schránok (gmail.com, azet.sk a podobné) odosielať nemôžu. 2. **Pridajte záznamy do DNS**: krok Záznamy v DNS vypíše presné záznamy: záznamy DKIM (CNAME) sú povinné, SPF a DMARC (TXT) odporúčané. Pridáte ich u správcu domény alebo ich pošlete tomu, kto vám doménu spravuje. Keď záznamy pri novej doméne ešte nevidíte, dokončujeme jej nastavenie na našej strane a objavia sa tu samy. 3. **Spustite kontrolu**: krok Kontrola overí každý záznam a ukáže, ktorý je v poriadku, ktorý chýba a ktorý je chybný. Zmeny v DNS sa môžu prejaviť až o niekoľko hodín. 4. **Pridajte adresy odosielateľa**: v kroku Adresy odosielateľa založíte adresy, z ktorých budú chodiť kampane, napríklad novinky@vasafirma.sk, a adresu na odpovede. 5. **Nastavte testovacie adresy**: v Nastaveniach › Odosielanie uložte adresy, na ktoré smú odchádzať testovacie e-maily, a pošlite si test. ## Čo ďalej pomáha • **Postupný nábeh**: nový účet posiela prvé dni len časť denného limitu a limit rastie po krokoch, plný objem dosiahne za 4 týždne. Poštové služby tak odosielateľa spoznávajú postupne. • **Tempo podľa poštových služieb**: e-maily odchádzajú v dávkach a s limitmi za minútu pre jednotlivé služby. • **Stráženie kampaní**: kampaň sa v predvolenom nastavení sama pozastaví, keď podiel odhlásení, nedoručiteľných adries alebo sťažností prekročí bezpečnú hranicu. • **Čistá databáza**: nedoručiteľné adresy a sťažnosti sa potlačia samy a kampane v predvolenom nastavení vynechajú neaktívne kontakty. • **Správy DMARC**: súhrnné správy DMARC ukazujú, koľko e-mailov z vašich domén prešlo kontrolou SPF, DKIM a DMARC a odkiaľ odchádzali. Ich načítanie do Štatistík › DMARC zatiaľ zapíname na požiadanie, napíšte nám. • **Kontrola obsahu**: antispamová kontrola v editore upozorní na rizikové frázy, skracovače odkazov, chýbajúce odhlásenie a ďalšie nálezy a pri každom poradí, ako ho opraviť. Pojmy z návodu: [doručiteľnosť](https://www.postarna.sk/slovnik#dorucitelnost), [warm-up](https://www.postarna.sk/slovnik#warm-up-zahrievanie-odosielania), [soft a hard bounce](https://www.postarna.sk/slovnik#hard-bounce). --- # Segmentácia zákazníkov v e-mailingu Jeden e-mail pre všetkých je najjednoduchší, ale málokedy najlepší. Kto nakúpil včera, nepotrebuje rovnakú ponuku ako ten, kto nenakúpil rok. [Segment](https://www.postarna.sk/slovnik#segment) vyberie kontakty podľa pravidiel a prepočítava sa sám, takže kampaň vždy dostanú tí správni. ## Príklady segmentov pre e-shop • **Noví zákazníci**: práve jedna objednávka, a to za posledných 30 dní. Hodí sa na sériu po prvom nákupe. • **Verní zákazníci**: tri a viac objednávok. Dostanú novinky ako prví. • **Zákazníci, ktorí prestávajú nakupovať**: posledná objednávka pred viac ako 120 dňami. Kandidáti na [win-back](https://www.postarna.sk/navody/win-back). • **Kupujúci značky alebo kategórie**: objednali produkt danej značky alebo kategórie, ak objednávky tieto údaje obsahujú (značku má export objednávok zo Shoptetu, kategóriu zapíšete cez API). • **Aktívni odberatelia**: angažovanosť A alebo B. Vhodní na častejšie rozosielky. • **Firmy**: kontakty s vyplneným IČO. Poštárna má pripravené predvolené segmenty, napríklad kupujúcich za posledných 12 mesiacov, kupujúcich pred 13 až 24 mesiacmi, firemných zákazníkov a kontakty aktívne za posledných 90 dní. ## Postup krok za krokom {#postup} 1. **Otvorte segmenty**: v Kontakty a zoznamy › Segmenty založte nový segment a vyberte e-shop. 2. **Pridajte pravidlá**: zvoľte typ pravidla, napríklad Posledná objednávka, počet alebo hodnota objednávok, objednaný produkt, angažovanosť, zoznam, súhlas s účelom spracúvania, reakcia na kampaň alebo pole kontaktu. 3. **Spojte pravidlá**: pravidlá spojíte cez A (musia platiť všetky) alebo ALEBO (stačí jedno) a môžete ich vnárať do skupín. 4. **Skontrolujte počet**: segment ukáže, koľko kontaktov doň patrí. Upravujte pravidlá, kým skupina nezodpovedá tomu, čo chcete. 5. **Použite segment**: v sprievodcovi kampaňou vyberte segment ako príjemcov. Rovnaké pravidlá použijete aj vo filtri spúšťača automatizácie. ## Tipy • Hodnota objednávok sa počíta zvlášť v eurách a v korunách, nikdy sa nesčítava. • Segment nahradí ručné zoznamy, ktoré by niekto musel udržiavať. Ručný zoznam používajte pre ľudí, ktorí sa k niečomu sami prihlásili. • Začnite dvoma alebo troma segmentmi a sledujte, ako sa líši miera prekliku a objednávky. Až potom pridávajte ďalšie. Pre vývojárov: [Zoznamy a segmenty v API dokumentácii](https://www.postarna.sk/docs/api/lists-and-segments). --- # Slovník pojmov e-mailového marketingu Krátke a presné vysvetlenie pojmov, na ktoré narazíte pri rozosielaní newsletterov a automatických e-mailov. Pri pojmoch, ktoré Poštárna priamo rieši, nájdete aj to, ako to v aplikácii funguje. Postupy krok za krokom sú v [návodoch](https://www.postarna.sk/navody). ## A/B test A/B test rozdelí príjemcov do dvoch alebo viacerých skupín a každej pošle inú verziu e-mailu, napríklad s iným predmetom alebo ponukou. Podľa výsledkov (otvorenia, kliky, objednávky) potom viete, ktorá verzia funguje lepšie. Aby bol výsledok spoľahlivý, má mať každá skupina dosť príjemcov a verzie sa majú líšiť len v jednej veci. **V Poštárni:** v automatizácii rozdelí uzol A/B test kontakty podľa zadaných percent až do 10 vetiev. Každý e-mail vo vetve má vlastné štatistiky, takže vetvy porovnáte vedľa seba. ## Angažovanosť kontaktu Angažovanosť hovorí, ako kontakt na e-maily reaguje: či ich otvára, kliká a nakupuje. Pomáha posielať viac tým, ktorí o e-maily stoja, a šetriť neaktívne kontakty, ktoré zhoršujú doručiteľnosť. **V Poštárni:** každý kontakt má angažovanosť A až E (od Veľmi aktívny po Neaktívny) alebo N (Bez dát). Počíta sa raz týždenne z reakcií za posledných 180 dní a kontakt s objednávkou za posledných 30 dní je vždy v skupine A. Podľa angažovanosti môžete stavať segmenty a kampaň vie neaktívne kontakty vynechať. ## Automatizácia Automatizácia (scenár) posiela e-maily sama, keď nastane určitá udalosť alebo príde určitý deň: prihlásenie na odber, objednávka, opustený košík, meniny alebo narodeniny. Raz ju nastavíte a potom beží pre každý kontakt zvlášť, v správnom okamihu. **V Poštárni:** scenár skladáte na plátne z uzlov: spúšťač (napríklad Pri udalosti, V plánovanom čase, Meniny, narodeniny, výročie, Kúpte si znova), Čakanie, Podmienka, Odoslať e-mail, Zmena v zozname, Webhook a ďalšie. Pred zapnutím sa dá scenár otestovať bez odoslania. ## BIMI BIMI (Brand Indicators for Message Identification) je štandard, podľa ktorého môžu niektoré poštové služby zobraziť pri e-maile logo odosielateľa. Predpokladom je doména zabezpečená cez DMARC s prísnou politikou (quarantine alebo reject) a záznam BIMI v DNS s logom vo formáte SVG; časť služieb vyžaduje aj overený certifikát loga. ## Blacklist Blacklist je zoznam adries, na ktoré sa nikdy nič neposiela, bez ohľadu na zoznamy a segmenty. Patria naň adresy, ktoré o to výslovne požiadali, alebo adresy, na ktoré písať nechcete. **V Poštárni:** adresu pridáte na blacklist pri kontakte alebo importom súboru blacklistu. Blacklist je súčasťou potlačenia (suppression), takže na adresu neodíde ani kampaň, ani automatický e-mail. ## CTOR CTOR (click-to-open rate) je podiel otvorených e-mailov, v ktorých príjemca klikol. Hovorí, ako dobre obsah e-mailu presvedčil tých, ktorí ho otvorili, nezávisle od predmetu. **V Poštárni:** CTOR = unikátne prekliky / unikátne otvorenia, v štatistikách každej kampane a každého e-mailu automatizácie. ## DKIM DKIM (DomainKeys Identified Mail) je elektronický podpis e-mailu. Odosielací server e-mail podpíše a príjemca podľa verejného kľúča v DNS vašej domény overí, že e-mail naozaj prišiel od vás a cestou sa nezmenil. **V Poštárni:** sprievodca v Nastaveniach › Odosielanie vypíše záznamy DKIM (CNAME), ktoré pridáte do DNS domény, a v kroku Kontrola overí, že sú správne. Bez overenej domény z nej Poštárna neodosiela. ## DMARC DMARC (Domain-based Message Authentication, Reporting and Conformance) je pravidlo v DNS domény, ktoré poštovým službám hovorí, čo robiť s e-mailom, ktorý neprejde kontrolou SPF alebo DKIM: doručiť (p=none), dať do spamu (p=quarantine) alebo odmietnuť (p=reject). Zároveň určuje, kam posielať súhrnné správy o tom, kto z vašej domény odosiela. **V Poštárni:** sprievodca odosielaním odporučí predvolený záznam DMARC a overí ho. Načítanie súhrnných správ DMARC do Štatistík › DMARC zatiaľ zapíname na požiadanie. ## Doručiteľnosť Doručiteľnosť (deliverability) vyjadruje, koľko e-mailov dorazí do doručenej pošty, a nie do spamu alebo nikam. Ovplyvňuje ju overenie domény (SPF, DKIM, DMARC), reputácia odosielateľa, kvalita databázy, množstvo sťažností a obsah e-mailu. **V Poštárni:** sprievodca nastavením odosielania overí doménu, nový účet zvyšuje denný objem postupne, e-maily odchádzajú v tempe prispôsobenom jednotlivým poštovým službám a kampaň sa sama zastaví, keď rastie podiel sťažností, odhlásení alebo nedoručiteľných adries. ## Double opt-in Double opt-in je prihlásenie na odber v dvoch krokoch: človek vyplní formulár a potom potvrdí odber kliknutím na odkaz v e-maile. Tak je isté, že adresa existuje a patrí tomu, kto sa prihlásil, a máte doložený súhlas. **V Poštárni:** formuláre používajú double opt-in v predvolenom nastavení. Kontakt čaká na potvrdenie, odkaz platí 7 dní a k prihláške sa uloží IP adresa, prehliadač, stránka a presné znenie súhlasu. Odhlásený kontakt sa môže znova prihlásiť len cez potvrdenie. Postup je v návode [Formulár s potvrdením odberu](https://www.postarna.sk/navody/formular-double-opt-in). ## Hard bounce Hard bounce je trvalá nedoručiteľnosť: schránka neexistuje, doména neexistuje alebo server adresu natrvalo odmieta. Na takú adresu sa už nemá posielať. **V Poštárni:** adresa s hard bounce sa hneď potlačí a žiadny ďalší e-mail na ňu neodíde. Kampaň sa v predvolenom nastavení sama pozastaví, keď podiel nedoručiteľných adries prekročí 1 % (po prvých 200 odoslaných). ## Konverzia z e-mailu Konverzia je objednávka, ktorú priviedol e-mail. Zvyčajne sa počíta objednávka po prekliku z e-mailu v určitom čase (atribučné okno), aby bolo vidieť, koľko kampaň alebo automatizácia zarobila. **V Poštárni:** objednávka do 24 hodín od prekliku je priama konverzia, od 24 hodín do 5 dní od prekliku alebo do 24 hodín od otvorenia asistovaná; počíta sa posledný preklik. Tržby sa ukazujú zvlášť v eurách a v korunách a zrušené objednávky sa nepočítajú. ## List hygiene (čistenie databázy) List hygiene je pravidelné čistenie zoznamu kontaktov: odstránenie nedoručiteľných adries, adries so sťažnosťou a dlhodobo neaktívnych kontaktov. Čistá databáza znamená menej nedoručiteľných e-mailov, menej sťažností a lepšiu doručiteľnosť. **V Poštárni:** nedoručiteľné adresy a sťažnosti sa potlačia samy. Kampaň v predvolenom nastavení vynechá neaktívne kontakty (angažovanosť E) a import preskočí neplatné adresy. ## Miera otvorenia (open rate) Miera otvorenia je podiel doručených e-mailov, ktoré príjemcovia otvorili. Meria sa obrázkovým pixelom, preto ju skresľujú služby, ktoré obrázky sťahujú samy (napríklad ochrana súkromia v Apple Mail), a príjemcovia s vypnutými obrázkami. **V Poštárni:** miera otvorenia = unikátne otvorenia / doručené e-maily. Strojové otvorenia sa do nej nepočítajú a preklik sa počíta aj ako otvorenie. ## Miera prekliku (CTR) Miera prekliku (click-through rate) je podiel e-mailov, v ktorých príjemca klikol na odkaz. Spoľahlivejšie ako otvorenie ukazuje skutočný záujem o obsah. **V Poštárni:** CTR = unikátne prekliky / odoslané e-maily. Strojové kliky (bezpečnostné skenery odkazov) sa nepočítajú. ## Newsletter Newsletter je e-mail, ktorý posielate pravidelne odberateľom: novinky, ponuky, články alebo tipy. Na rozdiel od automatického e-mailu ho odosielate ručne ako kampaň a dostanú ho všetci vo vybranom zozname alebo segmente. **V Poštárni:** newsletter je e-mailová kampaň. Návod na prvú rozosielku je v článku [Ako poslať prvý newsletter](https://www.postarna.sk/navody/prvy-newsletter). ## Odhlásenie z odberu Každý obchodný e-mail musí obsahovať jednoduchý spôsob, ako sa odhlásiť. Veľké poštové služby navyše vyžadujú odhlásenie jedným kliknutím priamo v aplikácii pošty (hlavička List-Unsubscribe podľa RFC 8058). **V Poštárni:** každý e-mail kampane a automatizácie má odkaz na odhlásenie aj hlavičku na odhlásenie jedným kliknutím. Odhlasovacia stránka sa môže opýtať na dôvod a ukázať nastavenie odberu. Odhlásenému kontaktu Poštárna už nič nepošle. ## Opustený košík Opustený košík je situácia, keď zákazník vloží tovar do košíka a objednávku nedokončí. Automatický e-mail mu po čase košík pripomenie a často privedie späť časť objednávok, ktoré by inak prepadli. **V Poštárni:** jeden riadok v pätičke e-shopu (Webtracking) posiela do Poštárne košíky zákazníkov, ktorých e-shop pozná, a spúšťač Každá zmena v košíku spustí scenár. Návod: [Opustený košík krok za krokom](https://www.postarna.sk/navody/opusteny-kosik). ## Oslovenie v 5. páde V češtine sa v oslovení používa 5. pád (vokatív): Petře, Lucie, pane Nováku. Slovenčina vokatív bežne nepoužíva, oslovuje sa v 1. páde (Peter, pán Novák), preto pri slovenských kontaktoch netreba nič skloňovať. **V Poštárni:** značka `{{df_salution}}` vloží pri českých menách oslovenie v 5. páde podľa českých pravidiel a výnimiek. Hodnota vyplnená pri kontakte má prednosť a slovenské mená sa neskloňujú. ## Personalizácia Personalizácia prispôsobí obsah e-mailu konkrétnemu príjemcovi: oslovenie menom, produkty podľa jeho nákupov, jeho zľavový kód alebo obsah podľa jazyka. Personalizované e-maily bývajú relevantnejšie ako jeden text pre všetkých. **V Poštárni:** šablóny vedia premenné kontaktu, podmienky a cykly, produkty z feedu, objednávky kontaktu a jednorazové zľavové kódy. ## Preheader Preheader je krátky text, ktorý poštová aplikácia ukáže v prehľade správ hneď za predmetom. Dopĺňa predmet a ovplyvňuje, či príjemca e-mail otvorí. **V Poštárni:** preheader zadáte v sprievodcovi kampaňou hneď pod predmet, najviac 200 znakov. ## RFM analýza RFM rozdelí zákazníkov podľa troch údajov: ako nedávno nakúpili (recency), ako často nakupujú (frequency) a koľko minuli (monetary). Z kombinácie vzniknú skupiny, napríklad verní zákazníci, noví zákazníci alebo zákazníci, ktorí prestávajú nakupovať, a každej môžete písať inak. ## Segment Segment je skupina kontaktov vybraná podľa pravidiel, napríklad zákazníci, ktorí nakúpili za posledných 12 mesiacov, alebo odberatelia, ktorí otvorili poslednú kampaň. Na rozdiel od ručného zoznamu sa segment počíta z dát. **V Poštárni:** pravidlá segmentu môžu byť podľa polí kontaktu, zoznamov, počtu a hodnoty objednávok, poslednej objednávky, objednaných produktov, angažovanosti, súhlasov a reakcií na kampane, spojené cez A a ALEBO. Návod: [Segmentácia zákazníkov](https://www.postarna.sk/navody/segmentacia-zakaznikov). ## Soft bounce Soft bounce je dočasná nedoručiteľnosť, napríklad plná schránka alebo krátkodobý výpadok servera. Jeden soft bounce nie je dôvod adresu mazať, opakovaný však ukazuje na problém. **V Poštárni:** adresa sa v predvolenom nastavení potlačí po 3 soft bounce za sebou. Úspešné doručenie počítadlo vynuluje. ## Soft opt-in (zákaznícka výnimka) Soft opt-in je zákonná výnimka, podľa ktorej smie e-shop posielať obchodné oznámenia o podobných produktoch svojim zákazníkom aj bez výslovného súhlasu, ak im to pri nákupe oznámil a dal možnosť odmietnuť. Každý e-mail potom musí ponúknuť odhlásenie. **V Poštárni:** výnimka sa nastavuje po e-shopoch. Slovenský e-shop má zo zákona limit 12 mesiacov od poslednej dokončenej objednávky (zákon č. 452/2021 Z. z.), pri ostatných e-shopoch lehota neplatí, kým ju firma nenastaví (1 až 120 mesiacov). Kontaktu, ktorému lehota uplynula, kampane ani automatizácie nič nepošlú. ## Spam filter Spam filter rozhoduje, či e-mail dorazí do doručenej pošty, alebo do spamu. Hodnotí overenie domény, reputáciu odosielateľa, reakcie príjemcov aj obsah: podozrivé frázy, pomer textu a obrázkov, skracovače odkazov alebo chýbajúce odhlásenie. **V Poštárni:** kontrola obsahu pred odoslaním vypočíta skóre podľa vlastných pravidiel (slová v predmete, frázy v slovenčine, češtine a angličtine, veľké písmená, obrázky, odkazy, skrytý text, veľkosť a odkaz na odhlásenie) a ukáže, čo opraviť. ## SPF SPF (Sender Policy Framework) je záznam v DNS domény, ktorý vymenuje servery oprávnené posielať e-maily za túto doménu. Poštová služba podľa neho rozpozná podvrhnutý e-mail. **V Poštárni:** sprievodca v Nastaveniach › Odosielanie odporučí záznam SPF pre vašu doménu a v kroku Kontrola overí, či je v DNS. ## Sťažnosť na spam Sťažnosť vznikne, keď príjemca označí e-mail tlačidlom Spam. Poštové služby sťažnosti prísne sledujú: už podiel okolo 0,1 % zhoršuje doručiteľnosť. **V Poštárni:** adresa so sťažnosťou sa hneď potlačí a kampaň sa v predvolenom nastavení sama pozastaví, keď podiel sťažností prekročí 0,1 %. ## Strojové otvorenia Strojové otvorenie je otvorenie alebo klik, ktorý neurobil človek: obrázky stiahne poštová služba sama, bezpečnostný skener prejde odkazy alebo sa e-mail načíta v proxy. Skresľuje mieru otvorenia aj prekliku. **V Poštárni:** strojové otvorenia a kliky sa ukladajú zvlášť a do štatistík ani do angažovanosti sa nepočítajú. Štatistika ukáže, pri koľkých e-mailoch prebehlo len strojové otvorenie. ## Súhlas so spracúvaním (GDPR) Na posielanie obchodných oznámení potrebujete súhlas alebo iný právny dôvod a musíte vedieť doložiť, kedy a ako ste ho získali. Podľa GDPR má človek právo súhlas odvolať, požiadať o výpis svojich údajov aj o ich vymazanie. **V Poštárni:** súhlasy sa evidujú podľa účelov spracúvania a každá zmena sa zapíše do histórie s časom, IP adresou a znením súhlasu. Pri kontakte sa dajú stiahnuť všetky dáta alebo vykonať vymazanie na žiadosť. ## Transakčný e-mail Transakčný e-mail posiela e-shop alebo aplikácia ako priamu reakciu na úkon zákazníka: potvrdenie objednávky, faktúra, obnova hesla alebo informácia o doručení. Na rozdiel od obchodného oznámenia sa posiela aj bez marketingového súhlasu, ale nemá obsahovať reklamu. ## Unikátny zľavový kód Unikátny zľavový kód je jednorazový kód, ktorý dostane len jeden príjemca. Na rozdiel od jedného kódu pre všetkých sa nedá zdieľať a viete, kto ho použil. **V Poštárni:** kódy z e-shopu nahráte do zásobníka kupónov a každý e-mail vezme nový voľný kód, ktorý sa kontaktu priradí. Hodí sa na meniny, narodeniny a návrat zákazníkov. ## Warm-up (zahrievanie odosielania) Warm-up je postupné zvyšovanie počtu odoslaných e-mailov z novej domény alebo IP adresy. Poštové služby nedôverujú odosielateľovi, ktorý z ničoho začne posielať tisíce e-mailov denne, preto sa objem zvyšuje v priebehu týždňov. **V Poštárni:** nový účet posiela prvé dni len časť denného limitu a limit rastie po krokoch, plný objem dosiahne za 4 týždne od prvého ostrého odoslania. ## Webhook Webhook je adresa vášho systému, na ktorú iná aplikácia sama pošle správu, keď sa niečo stane, napríklad nový kontakt, odhlásenie alebo preklik. Nemusíte sa tak stále dopytovať cez API. **V Poštárni:** účtové webhooky nastavíte v Nastaveniach › Dátové zdroje › Webhooky alebo cez API a posielajú udalosti nový a zmenený kontakt, odhlásenie, odoslaný e-mail, stav doručenia, otvorenie a preklik. V automatizácii je navyše uzol Webhook. Podrobnosti sú v [API dokumentácii](https://www.postarna.sk/docs/api/webhooks). ## Win-back (návrat zákazníkov) Win-back je séria e-mailov pre zákazníkov, ktorí dlho nenakúpili, alebo odberateľov, ktorí prestali reagovať. Pripomenie značku, ponúkne dôvod vrátiť sa a pri tých, ktorí nereagujú, pomôže rozhodnúť, či ich ďalej oslovovať. **V Poštárni:** win-back postavíte ako automatizáciu so spúšťačom Opakovať a podmienkou na poslednú objednávku. Návod: [Win-back kampaň pre neaktívnych zákazníkov](https://www.postarna.sk/navody/win-back). --- # Integrácie Poštárne Poštárna sa napojí na e-shop a ďalšie systémy bez programovania tam, kde to ide, a cez otvorené API tam, kde potrebujete vlastné riešenie. Všetky napojenia nájdete v aplikácii v Nastaveniach › Dátové zdroje. ## Shoptet E-shop na Shoptete napojíte bez programovania: • **Import zákazníkov a odberateľov**: export zákazníkov alebo odberateľov newslettera zo Shoptetu nahráte v Kontakty a zoznamy › Importy. Pri exporte zákazníkov rozhoduje o každom riadku stĺpec súhlasu s newsletterom: kto súhlas nemá, je zákazník bez marketingového súhlasu a e-maily nedostáva. • **Feed objednávok**: adresu exportu objednávok (orders.csv) zadáte ako feed objednávok. Poštárna ho sťahuje každú hodinu a pri exporte orders.csv zo Shoptetu načítava objednávky posledných 3 dní každých 10 minút. Objednávky poháňajú automatizácie po nákupe, segmenty podľa nákupov a tržby v štatistikách. Prvé stiahnutie histórie automatizácie nespúšťa. • **Feed zákazníkov**: export zákazníckych účtov ako feed načíta zákazníkov e-shopu do Poštárne a s objednávkami doplní dáta zákazníkov: v Nastaveniach › E-shopy tlačidlom Doplniť údaje vyplníte prázdne polia kontaktov (meno, telefón, firmu, adresu, jazyk, meniny a oslovenie), najprv uvidíte náhľad. Zákazník tým nevzniká ako odberateľ a nezískava súhlas. • **Webtracking košíka**: jeden riadok v pätičke e-shopu posiela košíky známych zákazníkov pre [opustený košík](https://www.postarna.sk/navody/opusteny-kosik). • **Pop-up formuláre**: pop-up vie skryť prihlásených zákazníkov a zákazníkov na stránke po objednávke. ## Produktové feedy Produktový feed vo formáte Google Merchant, Heureka.cz alebo Zboží.cz (XML) zadáte adresou. Produkty z feedu potom vkladáte do e-mailov v Magic Editore (obrázok, názov, cena a odkaz sa doplnia samy) a párujú sa s nimi položky objednávok. Pri feede môžete zapnúť automatické sťahovanie raz denne; limit je 20 MB a 50 000 položiek. ## Články z blogu (RSS a Atom) Článkový feed vo formáte RSS 2.0 alebo Atom, napríklad blog e-shopu, ponúkne v editore výber článkov do newslettera. ## Import CSV Kontakty z iného systému nahráte ako CSV (oddeľovač bodkočiarka, čiarka alebo tabulátor, kódovanie UTF-8 alebo Windows-1250). Poštárna navrhne priradenie stĺpcov podľa hlavičky v slovenčine, češtine aj angličtine, neplatné adresy preskočí a odhlásené adresy nikdy znova neprihlási. Import vie kontakty pridať alebo aktualizovať, len aktualizovať, odhlásiť z vybraných zoznamov, z vybraných zoznamov odobrať alebo adresy pridať na blacklist. Postup cez API: [Import kontaktov](https://www.postarna.sk/docs/api/recipe-import-contacts). ## Prechod zo SmartEmailingu Kontakty, zoznamy, odhlásenia, blacklist, súhlasy, šablóny a názvy automatizácií ako koncepty prenesiete sami pomocou API kľúča, v SmartEmailingu sa nič nezmení. Voliteľne beží hodinová synchronizácia, kým posielate z oboch systémov. Návod: [Prechod zo SmartEmailingu](https://www.postarna.sk/navody/prechod-zo-smartemailingu). ## API kompatibilné so SmartEmailingom Integrácia napísaná pre REST API v3 SmartEmailingu funguje s Poštárňou po zmene adresy, používateľského mena a kľúča: rovnaké cesty, obálky, chyby a stránkovanie na čítanie kontaktov, zoznamov a vlastných polí, účtové webhooky a vybrané CSV štatistiky. Kontakty a zoznamy cez API v3 zatiaľ nezapisujete, na to slúži API v1. Podrobnosti: [kompatibilita so SmartEmailingom](https://www.postarna.sk/docs/api/smartemailing). ## API v1 Úplné REST API, rovnaké, aké používa webová aplikácia: kontakty a súhlasy, zoznamy a segmenty, šablóny, kampane, automatizácie, objednávky, feedy a zľavové kupóny. Prihlásenie API kľúčom z Nastavení › Dátové zdroje › API kľúče, popis v OpenAPI 3.1. Objednávky z iného e-shopu alebo pokladne zapíšete cez API, pozri [Objednávky, feedy a kupóny](https://www.postarna.sk/docs/api/orders-feeds-coupons). Začnite [API dokumentáciou](https://www.postarna.sk/docs/api). ## Webhooky Účtové webhooky nastavíte v Nastaveniach › Dátové zdroje › Webhooky (aj s tlačidlom Otestovať) alebo cez API a pošlú na vašu adresu udalosť, keď vznikne alebo sa zmení kontakt, kontakt sa odhlási, e-mail odíde, zmení sa stav doručenia alebo príjemca e-mail otvorí či klikne. Strojové otvorenia a kliky webhook neposiela. V automatizácii je navyše uzol Webhook. Podrobnosti: [webhooky](https://www.postarna.sk/docs/api/webhooks). ## MCP pre AI asistentov Server MCP (Model Context Protocol) prepojí Poštárnu s AI asistentmi, ako sú ChatGPT, Claude alebo Cursor. Asistent sa prihlási cez OAuth alebo API kľúčom a vie pracovať s kontaktmi, zoznamami, segmentmi, šablónami, kampaňami, automatizáciami, formulármi, importmi a štatistikami. Odoslanie skutočným ľuďom a mazanie vždy vyžaduje náhľad a potvrdenie. Podrobnosti: [MCP pre AI asistentov](https://www.postarna.sk/docs/api/mcp). --- # API dokumentácia Poštárne Poštárna je platforma na e-mail marketing so štatistikami pre firmy aj e-shopy v Česku a na Slovensku. Cez API urobíte to isté, čo v aplikácii: správu kontaktov a súhlasov, zoznamov a segmentov, písanie šablón, odosielanie kampaní, stavbu automatizácií, prijímanie objednávok, feedov a kupónov a nastavenie webhookov. Dokumentácia je napísaná tak, aby podľa nej človek aj AI agent napísal funkčnú integráciu na prvý pokus, bez skúšania naslepo. ## Tri rozhrania | Rozhranie | Adresa | Na čo | |---|---|---| | **API v1** | `https://www.postarna.cz/api/v1/tenants/{tenant}/...` | Celé API Poštárne, rovnaké, aké používa webová aplikácia. JSON, prihlásenie API kľúčom. | | **API v3 kompatibilné so SmartEmailingom** | `https://www.postarna.cz/api/v3/...` a `/api/csv/...` | Rovnaké cesty, obálky a chyby ako REST API v3 SmartEmailingu. Čítanie kontaktov, zoznamov a polí, účtové webhooky, CSV štatistiky. | | **Server MCP** | `https://www.postarna.cz/mcp` | Model Context Protocol pre AI asistentov (ChatGPT, Claude, Cursor a ďalšie). | Rovnaké API odpovedá aj na `https://www.postarna.sk`. ## Najdôležitejšie pravidlá na jednom mieste • **Prihlásenie**: API kľúč `pst_...` v hlavičke `Authorization: Bearer pst_...` (alebo HTTP Basic: e-mail člena firmy a kľúč). Kľúč vytvoríte v aplikácii v Nastavenia › Dátové zdroje › API kľúče. Podrobne v [Začíname](https://www.postarna.sk/docs/api/getting-started). • **Firma v ceste**: `{tenant}` je verejné ID firmy (UUID). Zistíte ho volaním `GET /api/v3/account-info` (pole `data.guid`) alebo na stránke API kľúčov. • **JSON**: ID sú reťazce, časy ISO 8601 v UTC, peniaze desatinný reťazec vedľa meny. **CZK a EUR sa nikdy nesčítavajú ani neprevádzajú.** Pozrite [Pravidlá API](https://www.postarna.sk/docs/api/conventions). • **Chyby**: `{"error": {"code", "message", "params"}}`, `code` je stály strojový kód, `message` pomenúva pole. Každý kód s významom a nápravou je v [Chyby a limity](https://www.postarna.sk/docs/api/errors-and-limits). • **Limity**: na firmu zásobník 2 500 požiadaviek doplňovaný 4 za sekundu a 100 000 za deň; hlavičky `X-RateLimit-*`, po prekročení 429 s `Retry-After`. • **Bezpečnosť odosielania**: odhlásenému, vrátenému alebo potlačenému kontaktu Poštárna nikdy nič nepošle. Skôr než pošlete skutočným príjemcom, spočítajte ich (`POST .../campaigns/audience`) a automatizáciu otestujte (`POST .../automations/{id}/test`). ## Pre AI agentov • [`/llms.txt`](https://www.postarna.cz/llms.txt): stručný rozcestník celej dokumentácie v Markdowne. • [`/llms-full.txt`](https://www.postarna.cz/llms-full.txt): všetky návody, koncepty a recepty v jednom súbore a zoznam všetkých operácií. • [`/api/openapi.json`](https://www.postarna.cz/api/openapi.json): OpenAPI 3.1 so všetkými operáciami a schémami. Len jednu skupinu načítate parametrom `?tag=`, napríklad `?tag=Automations` alebo `?tag=Contacts,Lists`. • Graf automatizácie, podmienky a časové údaje majú presné schémy v [Referencii automatizácií](https://www.postarna.sk/docs/api/automation-reference); rovnaké pravidlá používa validátor servera. • Postup „najprv náhľad, potom akcia“: `POST /automations/validate`, `POST /automations/{id}/test`, `POST /campaigns/audience`. Pri trase s `x-mcp-confirm` v OpenAPI vždy počítajte s tým, že posiela skutočným ľuďom alebo maže dáta. ## Ako je dokumentácia usporiadaná • **Začíname**: [prvé volanie](https://www.postarna.sk/docs/api/getting-started) a [pravidlá API](https://www.postarna.sk/docs/api/conventions). • **Koncepty**: [firma a e-shopy](https://www.postarna.sk/docs/api/tenants-and-shops), [kontakty a súhlasy](https://www.postarna.sk/docs/api/contacts-and-consent), [zoznamy a segmenty](https://www.postarna.sk/docs/api/lists-and-segments), [šablóny a personalizácia](https://www.postarna.sk/docs/api/templates-and-personalization), [kampane](https://www.postarna.sk/docs/api/campaigns), [automatizácie](https://www.postarna.sk/docs/api/automations) a ich [referencia](https://www.postarna.sk/docs/api/automation-reference), [objednávky, feedy a kupóny](https://www.postarna.sk/docs/api/orders-feeds-coupons). • **Recepty**: hotové postupy s overenými požiadavkami a odpoveďami: [opustený košík](https://www.postarna.sk/docs/api/recipe-abandoned-cart), [séria po nákupe](https://www.postarna.sk/docs/api/recipe-post-purchase), [meniny](https://www.postarna.sk/docs/api/recipe-name-days), [návrat neaktívnych zákazníkov](https://www.postarna.sk/docs/api/recipe-win-back), [formulár s potvrdením](https://www.postarna.sk/docs/api/recipe-double-opt-in), [import kontaktov](https://www.postarna.sk/docs/api/recipe-import-contacts), [odoslanie kampane](https://www.postarna.sk/docs/api/recipe-send-campaign), [príjem webhookov](https://www.postarna.sk/docs/api/recipe-webhook-consumer). • **Integrácie**: [webhooky](https://www.postarna.sk/docs/api/webhooks), [MCP pre AI asistentov](https://www.postarna.sk/docs/api/mcp), [kompatibilita so SmartEmailingom](https://www.postarna.sk/docs/api/smartemailing). • **Referencia API**: [prehľad všetkých operácií](https://www.postarna.sk/docs/api/reference), [chyby a limity](https://www.postarna.sk/docs/api/errors-and-limits), stránka pre každú skupinu operácií a [história zmien](https://www.postarna.sk/docs/api/changelog). > **Overené príklady:** každá požiadavka a odpoveď v receptoch sa pri testoch Poštárne púšťa proti skutočnému serveru. Keď sa API zmení, test zlyhá a príklad sa opraví skôr, než zmena odíde. --- # Začíname Za päť minút budete mať kľúč, ID firmy a prvú odpoveď API. ## 1. Vytvorte API kľúč V aplikácii Poštárna otvorte **Nastavenia › Dátové zdroje › API kľúče** a zvoľte **Nový API kľúč**. • **Názov**: na čo kľúč slúži, napríklad „CRM synchronizácia“. • **Platnosť**: posledný deň platnosti (najdlhšie 730 dní dopredu), alebo bez obmedzenia. Kľúč, ktorý sa 180 dní nepoužije, sám prestane fungovať. • **Rola**: čo kľúč smie. Kľúč nikdy nedostane viac práv než človek, ktorý ho vytvára, a prestane fungovať, keď jeho autor odíde z firmy. • **Prístup**: **plný** (čítanie aj zmeny) alebo **len na čítanie** (len trasy, ktoré nič nemenia). Kľúč má tvar `pst_` a 43 znakov. **Zobrazí sa len raz**, Poštárna si ukladá len jeho odtlačok. Uložte ho do správcu hesiel alebo premennej prostredia, nikdy do kódu v repozitári. Firma môže mať najviac 20 platných kľúčov. ### Akú rolu kľúču dať Role určujú úroveň v jednotlivých moduloch (`none`, `read`, `full`). Každá operácia v [referencii](https://www.postarna.sk/docs/api/reference) uvádza modul a úroveň, ktorú potrebuje. | Rola | contacts | campaigns | content | settings | billing | |---|---|---|---|---|---| | `account_admin` (správca účtu) | full | full | full | full | full | | `marketing_manager` (marketing) | full | full | full | read | none | | `content_manager` (obsah) | none | read | full | none | none | | `data_analyst` (analytik) | read | read | read | none | none | | `developer` (vývojár) | none | read | none | read | none | | `finance` (financie) | none | none | none | none | full | • Na bežnú integráciu (kontakty, objednávky, kampane, automatizácie) stačí `marketing_manager`. • Účtové webhooky, feedy, kupóny, stavy objednávok a odosielacie domény potrebujú `settings` na úrovni `full`, teda rolu `account_admin`. • Rola `developer` **nevidí kontakty**; na integráciu s kontaktmi ju nepoužívajte samotnú. • Moduly `users` a `api_keys` (členovia, pozvánky, API kľúče, pripojené aplikácie) kľúč nikdy nedostane, ani s plným prístupom. Tieto trasy vrátia 403 `forbidden` / `api_key`. ## 2. Pripravte premenné prostredia ```bash title="Terminál" export POSTARNA_API_KEY="pst_vas_kluc_tu" # kľúč z kroku 1 export POSTARNA_USER="vas.email@example.sk" # e-mail člena firmy (len pre HTTP Basic) ``` Všetky príklady v dokumentácii čítajú kľúč z `POSTARNA_API_KEY` a ID firmy z `TENANT`. ## 3. Zistite ID firmy {#3-zjistete-id-firmy} Cesty API v1 obsahujú verejné ID firmy: `/api/v1/tenants/{tenant}/...`. Zistíte ho z API kompatibilného so SmartEmailingom, ktoré ID firmy nepotrebuje: ```bash title="Požiadavka: GET /api/v3/account-info" curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "status": "ok", "meta": [], "data": { "account_id": 4, "guid": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f", "username": "admin@example.cz", "firstname": null, "surname": null, "company": "Example s.r.o.", "phone": null } } ``` Hodnota `data.guid` je vaše `{tenant}`. Rovnaké ID zobrazuje aplikácia na stránke API kľúčov. ```bash title="Terminál" export TENANT="3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f" # data.guid z odpovede ``` ## 4. Prvé volanie API v1 E-shopy firmy (každý má svoju menu a jazyk; ID e-shopu budete potrebovať takmer všade): ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/shops" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "id": "7", "code": "cz", "displayName": "Example.cz", "domain": "example.cz", "currency": "CZK", "language": "cs", "active": true }, { "id": "8", "code": "sk", "displayName": "Example.sk", "domain": "example.sk", "currency": "EUR", "language": "sk", "active": true } ] } ``` Kontakty, dva na stránku: ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/contacts" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?pageSize=2" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [], "total": 0, "page": 1, "pageSize": 2 } ``` ## 5. Dve možnosti prihlásenia • **Bearer** (odporúčané): `Authorization: Bearer pst_...`. • **HTTP Basic**: užívateľské meno je e-mail aktívneho člena firmy, heslo je API kľúč. Funguje na API v1 aj v3 (takto sa prihlasuje aj SmartEmailing). Zoznam použiteľných e-mailov je na stránke API kľúčov. Cookie ani hlavičku CSRF API kľúč nepotrebuje; tie používa len webová aplikácia. ## 6. Keď niečo nejde Bez kľúča (alebo s neplatným, prepadnutým či zrušeným kľúčom) server odpovie 401: ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/shops" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops" ``` ```json title="Odpoveď: 401 Unauthorized" { "error": { "code": "unauthorized", "message": "" } } ``` Neplatný parameter vráti 400 `validation` a v `message` názov parametra: ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/contacts" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?pageSize=500" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 400 Bad Request" { "error": { "code": "validation", "message": "pageSize" } } ``` Všetky kódy chýb s významom a nápravou: [Chyby a limity](https://www.postarna.sk/docs/api/errors-and-limits). ## Čo ďalej • [Pravidlá API](https://www.postarna.sk/docs/api/conventions): formáty, stránkovanie, limity, opakovanie požiadaviek. • [Kontakty a súhlasy](https://www.postarna.sk/docs/api/contacts-and-consent): komu Poštárna smie písať. • Recepty: [opustený košík](https://www.postarna.sk/docs/api/recipe-abandoned-cart), [odoslanie kampane](https://www.postarna.sk/docs/api/recipe-send-campaign), [import kontaktov](https://www.postarna.sk/docs/api/recipe-import-contacts). --- # Pravidlá API Platí pre API v1 (`/api/v1/...`). API v3 kompatibilné so SmartEmailingom má vlastné obálky a formáty, popísané v [Kompatibilite so SmartEmailingom](https://www.postarna.sk/docs/api/smartemailing). ## Adresa a formát • Základ: `https://www.postarna.cz/api/v1`. Operácie firmy: `/api/v1/tenants/{tenant}/...`, kde `{tenant}` je verejné ID firmy (UUID). • Telo požiadaviek POST, PUT a PATCH je JSON (`Content-Type: application/json`, UTF-8). Iný typ obsahu = 415 `validation` / `contentType`, telo, ktoré nie je objekt JSON, = 400 `validation` / `body`. Výjimky: nahrávanie CSV a súborov prijíma aj `multipart/form-data`. • Odpovede sú JSON v UTF-8 (diakritika nie je escapovaná). Exporty a štatistiky zvládnu aj CSV (`format=csv`). • Jedno telo požiadavky má najviac 5 MB (väčšie = 413 `validation` / `size`); CSV súbor importu nahraný ako `multipart/form-data` až 64 MB. ## Dátové typy | Údaj | Formát | Príklad | |---|---|---| | ID objektu | reťazec číslic | `"1201"` | | ID firmy | UUID | `"3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f"` | | Čas | ISO 8601 v UTC s milisekundami | `"2026-10-01T08:00:00.000Z"` | | Kalendárny deň firmy | `YYYY-MM-DD` v časovej zóne firmy | `"2026-10-31"` | | Miestny čas v automatizáciách | `YYYY-MM-DDTHH:MM`, `HH:MM` | `"2026-12-01T09:00"`, `"08:00"` | | Peniaze | desatinný reťazec vedľa `currency` | `"1290.00"` a `"CZK"` | | Meniny kontaktu | `MM-DD` | `"10-31"` | • Časy zapisované do API (`sendAt`, `createdAt` objednávky) posielajte s časovou zónou (`Z` alebo `+02:00`). • Dni v segmentoch a podmienkach („za posledných 30 dní“) sú kalendárne dni v časovej zóne firmy (Europe/Prague, Europe/Bratislava). • **Meny sa nikdy nesčítavajú ani neprevádzajú.** Každý e-shop má jednu menu; objednávka v inej mene, než má jej e-shop, je chyba 400. Súčty (tržby, konverzie) sú vždy po menách. ## Stránkovanie, vyhľadávanie a triedenie • Zoznamy objektov majú `page` (od 1) a `pageSize` (1 až 100, východiskovo 25). Odpoveď je `{"items": [...], "total": 240, "page": 1, "pageSize": 25}`. • Prejdite všetky stránky, dokým `page * pageSize < total`. • `q` hľadá v názve alebo adrese bez ohľadu na veľkosť písmen a diakritiku (najviac 200 znakov). Pri automatizáciách `q=#123` nájde automatizáciu podľa ID. • `shop` obmedzí prehľad na jeden e-shop (ID e-shopu). • `sort` pri prehľadoch, ktoré ho majú: pole oddelené čiarkou, `-` na začiatku = zostupne, najviac 3 polia (`sort=name,-createdAt`). Východiskové triedenie je od najnovšieho. Neznáme pole = 400 `validation` / `sort`. ## Chyby Každá chyba má rovnaký tvar a vhodný HTTP stav: ```json title="Telo chyby" {"error": {"code": "conflict", "message": "version", "params": {"current": 4}}} ``` • `code`: stály strojový kód (`validation`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `unavailable` a ďalšie). Podľa neho sa rozhodujte. • `message`: technický údaj, obvykle názov poľa (`email`, `definition.1.0.listId`, `graph`) alebo dôvod (`version`, `status`). Nie je to text pre ľudí a môže byť prázdny. • `params`: podrobnosti, napríklad `issues` pri grafe automatizácie, `expected` a `actual` pri počte príjemcov, `reason`. • API neposiela texty pre ľudí; texty v češtine a slovenčine si skladá aplikácia. Úplný zoznam kódov s významom a nápravou: [Chyby a limity](https://www.postarna.sk/docs/api/errors-and-limits). ## Limity požiadaviek • Na firmu (všetky kľúče spolu): zásobník **2 500 požiadaviek**, ktorý sa doplňuje **4 požiadavkami za sekundu**, a **100 000 požiadaviek za deň** (doplňuje sa priebežne, žiadny reset o polnoci). • Každá odpoveď na požiadavku s kľúčom nesie `X-RateLimit-Limit`, `X-RateLimit-Remaining` a `X-RateLimit-Reset` (unixový čas, kedy bude zásobník zase plný) zásobníka, ktorému zostáva menej. • Po prekročení prichádza 429 `rate_limited` s hlavičkou `Retry-After` (za koľko sekúnd). Odmietnuté požiadavky sa nepočítajú. • Niektoré akcie majú vlastné limity (testovacie e-maily, udalosti kontaktu, MCP); sú v [Chybách a limitoch](https://www.postarna.sk/docs/api/errors-and-limits#limity-akci). ## Opakovanie požiadaviek a idempotencia {#opakovani-pozadavku-a-idempotence} API nepoužíva hlavičku `Idempotency-Key`. Po výpadku siete alebo chybe 5xx preto opakujte len to, čo je bezpečné opakovať: • **GET** opakujte vždy. • **PUT** nahrádza celý objekt (obsah šablóny, graf automatizácie, stavy objednávok): opakovanie s rovnakými dátami nič nepokazí; pri obsahu a grafe však sleduje verziu (pozrite nižšie). • **DELETE** opakujte; druhé volanie vráti 404, čo znamená „už zmazané“. • **POST /orders** je upsert podľa dvojice (`shopId`, `id` objednávky): opakovanie s rovnakými dátami vráti `change: "unchanged"`. • **POST /lists/{id}/members** je idempotentné: kontakt, ktorý je už členom, sa počíta do `alreadyMember`. • **POST /contacts**: druhé založenie rovnakej adresy vráti 409 `conflict` / `email`. Pred opakovaním kontakt vyhľadajte (`GET /contacts?q=adresa`) a prípadne upravte cez `PATCH`. • **POST /contact-events** idempotentné nie je: každá udalosť sa zapíše znovu. Po časovom limite skôr jednu udalosť straťte, než ju pošlite dvakrát. • **POST /campaigns/{id}/approve** chráni stav kampane: druhé schválenie vráti 409 `conflict` / `status`. • Pri 429 počkajte `Retry-After`; pri 5xx opakujte s rastúcim odstupom (1, 2, 4, 8 s) a najviac päťkrát. ## Súbežné úpravy (verzie) Obsah šablón a kampaní, pätičky a grafy automatizácií majú číslo verzie. Ukladanie posiela `baseVersion` = verziu, ktorú ste naposledy načítali. Keď medzitým uložil niekto iný, server vráti 409 `conflict` / `version` s `params.current`; načítajte objekt znovu, zlúčte zmeny a uložte s novou verziou. ## Oprávnenia • Každá operácia patrí do modulu (`contacts`, `campaigns`, `content`, `settings`, `billing`) a potrebuje úroveň `read` alebo `full`. Referencia to pri každej operácii uvádza. • Kľúč s prístupom len na čítanie dosiahne len na operácie s úrovňou `read` (aj POST, ktorý len počíta, napríklad náhľad segmentu). Inak 403 `forbidden` / `scope`. • Kľúč v cudzej firme: 403 `forbidden` / `tenant`. Chýbajúca rola: 403 `forbidden` s názvom modulu v `message`. Objekt inej firmy sa tvári ako neexistujúci (404). • Bez prihlásenej osoby (teda ani kľúčom) nejde: správa členov, pozvánok, API kľúčov a pripojených aplikácií, hlavný vypínač odosielania a zmeny tarifu. ## Neznáme polia Posielajte len zdokumentované polia. Väčšina trás neznáme polia ignoruje, niektoré ich odmietnu s názvom poľa v `message` (napríklad `POST /orders`), nastavenie uzlov automatizácie sa pri uložení zahodí. Nové polia v odpovediach môžu pribúdať, klient ich má ignorovať. --- # Firma a e-shopy ## Firma (tenant) Účet v Poštárni patrí **firme**. V API sa jej hovorí tenant a jej verejné ID (UUID) je v ceste každej operácie: `/api/v1/tenants/{tenant}/...`. • Dáta firiem sú od seba oddelené na úrovni databázy. Kľúč jednej firmy na ceste inej firmy dostane 403 `forbidden` / `tenant`, objekt inej firmy sa tvári ako neexistujúci (404). • Firma má členov s rolami (správca účtu, marketing, obsah, analytik, vývojár, financie). API kľúč patrí firme, pracuje s rolami, ktoré mu jeho autor dal, a nikdy nespravuje členov ani kľúče. • ID firmy zistíte z `GET /api/v3/account-info` (`data.guid`), pozrite [Začíname](https://www.postarna.sk/docs/api/getting-started#3-zjistete-id-firmy). ## E-shopy Firma má jeden alebo viac **e-shopov** (napríklad CZ v korunách a SK v eurách). E-shop určuje: • **menu** (`CZK` alebo `EUR`): objednávky, košíky, kupóny a podmienky o tržbách sú vždy v mene e-shopu, • **jazyk** (`cs` alebo `sk`): východiskový jazyk kontaktov a stránok pre príjemcov, • **odosielateľa** (overené adresy, `GET /senders`) a pätičku s identitou firmy, • **odkazovú doménu**, na ktorej bežia odhlásenie, nastavenie odberu a formuláre. ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/shops" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "id": "7", "code": "cz", "displayName": "Example.cz", "domain": "example.cz", "currency": "CZK", "language": "cs", "active": true }, { "id": "8", "code": "sk", "displayName": "Example.sk", "domain": "example.sk", "currency": "EUR", "language": "sk", "active": true } ] } ``` Ku ktorému e-shopu čo patrí: | Objekt | Väzba na e-shop | |---|---| | Kontakt | hlavný e-shop (`shopId`); zakladá sa vždy s e-shopom | | Zoznam | e-shop, alebo celá firma (`shopId: null`) | | Segment | vždy jeden e-shop; vyhodnocuje sa nad kontaktmi s týmto hlavným e-shopom | | Kampaň | jeden e-shop (odosielateľ, pätička, mena) | | Automatizácia | jeden e-shop; e-shop sa po založení nemení | | Objednávka, košík, kupóny, feed | jeden e-shop | Vypnutý e-shop (`POST /shops/{id}/disable`) nič nové neposiela: jeho automatizáciu nejde zapnúť a nové kampane neodídu. ## Zákaznická výnimka (soft opt-in) Zákazníkovi, ktorý u e-shopu nakúpil, smie e-shop za zákonných podmienok posielať obchodné oznámenia bez výslovného súhlasu. Poštárna to stráži po e-shopoch: • Slovenský e-shop má zo zákona limit 12 mesiacov od poslednej dokončenej objednávky (zákon č. 452/2021 Z. z., § 116 ods. 16), aj bez nastavenia. • Iný e-shop má výnimku vypnutú, dokým si ju firma nenastaví. • Čítanie a zmena: `GET /consent-settings`, `PATCH /consent-settings/{shopId}` s telom `{"months": 12}` (0 = vypnuté, 1 až 120 mesiacov). • Kontaktu, ktorému výnimka vypršala, kampane ani automatizácie nepošlú nič (v počte príjemcov ako `exception_expired`). ## Časová zóna Firma má časovú zónu (Europe/Prague alebo Europe/Bratislava). V nej sa počítajú kalendárne dni segmentov a podmienok, miestne časy automatizácií (`"08:00"`, `"2026-12-01T09:00"`) a dni v CSV štatistikách. Časy v JSON sú vždy v UTC. --- # Kontakty a súhlasy ## Kontakt Kontakt je jedna e-mailová adresa vo firme (adresa je vo firme jedinečná, bez ohľadu na veľkosť písmen). Má hlavný e-shop (`shopId`), profilové polia a stav. Profilové polia (názvy v API): `firstName`, `lastName`, `titleBefore`, `titleAfter`, `salutation`, `salutationFormal`, `vocativeFirstName` (oslovenie v 5. páde, napríklad „Petre“), `vocativeLastName`, `gender` (`f`, `m`, `null`), `language` (`cs`, `sk` ...), `company`, `companyId` (IČO), `phone`, `mobile`, `street`, `city`, `postalCode`, `country` (dve písmená), `birthday` (`YYYY-MM-DD`), `nameDay` (`MM-DD`), `note`, `affiliateId` a vlastné pole `customFields` (`{"": hodnota}`, ID polí z `GET /custom-fields`). ### Stav kontaktu (`status`) | Stav | Význam | Dostáva e-maily | |---|---|---| | `subscribed` | prihlásený | áno (ak nie je potlačený a nemá slabý súhlas) | | `pending` | čaká na potvrdenie odberu (double opt-in) | nie | | `unsubscribed` | odhlásený | nie, nikdy znovu bez nového potvrdenia | | `bounced` | adresa je nedoručiteľná | nie | | `complained` | označil e-mail ako spam | nie | | `customer` | zákazník bez marketingového súhlasu (vznikol z objednávky) | nie (len v rámci zákaznickej výnimky e-shopu) | **Poštárna nikdy znovu neoslovuje odhlásený, vrátený alebo potlačený kontakt.** Odhlásený kontakt sa znovu prihlási len novým potvrdením odberu (double opt-in), nikdy volaním API. ### Pôvod súhlasu (`consentBasis`) `double_opt_in` (potvrdil odber), `imported` (doložený súhlas zadaný ručne alebo importom), `soft_opt_in_customer` (zákaznická výnimka), `none`. Pole `consentWeak` = slabý súhlas; takým kontaktom kampane ani automatizácie nepíšu. ## Účely spracúvania a súhlasy Účel spracúvania (`purpose`) je druh súhlasu, napríklad „Zasielanie obchodných oznámení (newsletter)“. Každá firma má východiskový účel; zoznam vráti `GET /purposes`. • Súhlas kontaktu s účelom: `GET /contacts/{id}/purposes`, zápis `POST /contacts/{id}/purposes`, odvolanie `POST /contacts/{id}/purposes/{consentId}/withdraw`. • Kampaň môže vziať len kontakty s platným súhlasom (`onlyWithPurpose`), segmenty a podmienky automatizácií zvládnu pravidlo `purpose` / `contact_purpose`. ## Založenie kontaktu Kontakt cez API založíte len tak, keď máte **doložený súhlas** (napríklad z vlastného formulára alebo zmluvy). Telo musí obsahovať `purposeId` (účel, ku ktorému sa súhlas vzťahuje) a `consentConfirmed: true` (potvrdzujete, že súhlas máte doložený). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "email": "jana.novakova@example.cz", "shopId": "3", "purposeId": "2", "consentConfirmed": true, "firstName": "Jana", "lastName": "Nováková", "city": "Brno" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "1202", "email": "jana.novakova@example.cz", "firstName": "Jana", "lastName": "Nováková", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "3", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "Brno", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": null, "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-2", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` • Nový kontakt dostane `source: "manual"`, `consentBasis: "imported"` a jazyk e-shopu, ak nepošlete vlastný. • Adresa, ktorá je potlačená (odhlásená, vrátená, sťažnosť), vznikne s príslušným stavom a potlačenie zostáva. • `listIds` rovno pridá kontakt do ručných alebo formulárových zoznamov. • Adresa, ktorá už je kontaktom, vráti 409: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "email": "jana.novakova@example.cz", "shopId": "3", "purposeId": "2", "consentConfirmed": true } JSON ``` ```json title="Odpoveď: 409 Conflict" { "error": { "code": "conflict", "message": "email" } } ``` Keď doložený súhlas nemáte, použite **formulár s potvrdením** (double opt-in), pozrite [recept](https://www.postarna.sk/docs/api/recipe-double-opt-in). Kupujúci z objednávok ([`POST /orders`](https://www.postarna.sk/docs/api/orders-feeds-coupons)) dostanú stav `customer` a e-maily nedostávajú. ## Vyhľadávanie a úpravy ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/contacts" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?q=jana.novakova%40example.cz" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "id": "1202", "email": "jana.novakova@example.cz", "firstName": "Jana", "lastName": "Nováková", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "3", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": "active", "createdAt": "2026-10-01T08:00:00.000Z" } ], "total": 1, "page": 1, "pageSize": 25 } ``` `PATCH /contacts/{id}` mení profilové polia a vlastné polia, nikdy adresu, stav ani súhlas (400 `email`). Polia, ktoré upravil človek v aplikácii, importy a synchronizácie neprepíšu. ```bash title="Požiadavka: PATCH /api/v1/tenants/{tenant}/contacts/1202" curl -sS -X PATCH "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts/1202" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "phone": "+420 600 000 000", "customFields": {} } JSON ``` ```json title="Odpoveď: 200 OK" { "id": "1202", "email": "jana.novakova@example.cz", "firstName": "Jana", "lastName": "Nováková", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "3", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "+420 600 000 000", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "Brno", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": null, "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-2", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` Ďalšie filtre zoznamu kontaktov: `status`, `list` (ID zoznamu), `shop`, `engagement` (A až E, N), `source`, `createdFrom`, `createdTo`, `tab` a záporné varianty `stateOp=neq`, `listOp=neq` a ďalšie (pozrite [referencia kontaktov](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-list)). ## Odhlásenie, potlačenie a blacklist • `POST /contacts/{id}/unsubscribe` odhlási kontakt zo všetkého, ako by kliknul na odkaz v e-maile: stav `unsubscribed`, adresa sa potlačí, e-maily v poradí sa preskočia, zápis do historie súhlasov. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts/1202/unsubscribe" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts/1202/unsubscribe" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "note": "Požádala telefonicky" } JSON ``` ```json title="Odpoveď: 200 OK" { "id": "1202", "email": "jana.novakova@example.cz", "firstName": "Jana", "lastName": "Nováková", "status": "unsubscribed", "engagement": "N", "excluded": false, "shopId": "3", "suppressionReason": "unsubscribed", "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "+420 600 000 000", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "Brno", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": "2026-10-01T08:00:00.000Z", "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [ { "listId": "41", "name": "VIP zákazníci", "state": "confirmed", "changedAt": "2026-10-01T08:00:00.000Z", "listSize": 1 } ], "recentActivities": [ { "id": "consent-4", "type": "unsubscribed", "at": "2026-10-01T08:00:00.000Z", "title": "admin" }, { "id": "consent-3", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "suppressed" }, { "id": "consent-2", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` • **Potlačenie** (`suppressions`) je zoznam adries, na ktoré sa nesmie písať: odhlásenie, nedoručiteľné, sťažnosti a ručný blacklist. `GET /suppressions`, ručné pridanie `POST /suppressions` s `{"email", "detail"}`. ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/suppressions" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/suppressions" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "email": "jana.novakova@example.cz", "reason": "unsubscribed", "source": "admin", "detail": "", "blacklisted": false, "createdAt": "2026-10-01T08:00:00.000Z" } ], "total": 1, "page": 1, "pageSize": 25 } ``` • Potlačenie sa maže **len po jednom** (`DELETE /suppressions/{email}`), hromadné mazanie databázy odmietne. Blacklist kontaktu: `POST` a `DELETE /contacts/{id}/blacklist`; adresa potlačená z iného dôvodu vráti 409 `suppression_locked`. ## Osobné údaje (GDPR) • `GET /contacts/{id}/export`: všetky dáta kontaktu (profil, súhlasy, zoznamy, aktivity, objednávky). • `POST /contacts/{id}/erase` s telom `{"confirm": true}`: nevratný výmaz na žiadosť človeka. Kontakt, jeho súhlasy, členstvá a história zmiznú, adresa sa odstráni aj z odoslaných e-mailov, objednávok a záznamu súhlasov. Zostane len odtlačok adresy (nie adresa), aby ju import ani synchronizácia znovu nezaložili, a riadok potlačenia, ak sa adresa odhlásila alebo bola nedoručiteľná (pravidlo „nikdy znovu nepísať“). • `DELETE /contacts/{id}`: zmaže kontakt s jeho členstvami, súhlasmi a aktivitami; odoslané e-maily a záznamy zostanú s adresou a potlačenie sa nemení. Na žiadosť o výmaz používajte `erase`. ## Shrnutie: komu e-mail odíde E-mail kampane alebo automatizácie odíde len kontaktu, ktorý je súčasne: 1. v stave `subscribed`, 2. bez potlačenia (odhlásenie, nedoručiteľnosť, sťažnosť, blacklist), 3. bez slabého súhlasu, 4. pri zákaznickej výnimke ešte v jej lehote, 5. a pri kampani spĺňa jej publikum (zoznamy, segmenty, vylúčenie, účel). Kontroluje sa pri výbere príjemcov aj tesne pred odoslaním každého e-mailu. --- # Zoznamy a segmenty | | Zoznam | Segment | |---|---|---| | Členstvo | výslovné: kontakty do neho pridáte (ručne, formulárom, importom, automatizáciou) | podľa podmienok: kontakt je členom, dokým podmienky spĺňa | | E-shop | jeden e-shop, alebo celá firma | vždy jeden e-shop | | Typické použitie | odber newslettera, VIP klub, kontakty z akcie | „minuli vyše 3 000 Kč za rok“, „neotvorili 90 dní“ | | Kampaň | áno | áno | | Podmienka v automatizácii | `contact_in_list` | pravidlá segmentu priamo v podmienke | ## Zoznamy • `GET /lists`, `POST /lists`, `PATCH /lists/{id}`, `DELETE /lists/{id}`. • **Ručné zoznamy** (`manualMembers: true`): členov pridávate a odoberáte sami. • **Zoznamy napojené na e-shop** (`systemKind` `shop_contacts`, `shop_newsletter`, `shop_unsubscribed`) plní synchronizácia e-shopu; pridať alebo odobrať člena = 409 `conflict` / `locked`. • **Formulárové zoznamy** plnia formuláre, členov možno pridávať aj ručne. • `publicName` je názov zoznamu, ktorý kontakt uvidí na stránke nastavenia odberu. Stavy členstva: `confirmed` (potvrdený), `unconfirmed` (čaká na potvrdenie odberu), `unsubscribed` (odhlásil sa z tohto zoznamu), `removed` (odobraný). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/lists" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "VIP zákazníci", "publicName": "Novinky pro VIP", "shopId": null, "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "41", "name": "VIP zákazníci", "publicName": "Novinky pro VIP", "shopId": null, "systemKind": null, "locked": false, "manualMembers": true, "tags": [], "counts": { "total": 0, "byBucket": { "active": 0, "unconfirmed": 0, "unsubscribed": 0, "bounced": 0, "complained": 0, "blacklisted": 0 } }, "createdAt": "2026-10-01T08:00:00.000Z", "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } ``` ### Pridanie a odobranie členov `POST /lists/{id}/members` s `{"contactIds": [...]}` (1 až 1 000 ID): • už člen = `alreadyMember`, • kontakt odhlásený z tohto zoznamu, odhlásený celkovo, nedoručiteľný alebo potlačený = `skipped` (nikdy ho znovu neprihlási), • ostatné = `added` (kontakt čakajúci na potvrdenie sa pridá ako `unconfirmed`). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/lists/41/members" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists/41/members" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "contactIds": [ "1202" ] } JSON ``` ```json title="Odpoveď: 200 OK" { "added": 1, "alreadyMember": 0, "skipped": 0 } ``` • `POST /lists/{id}/members/remove` člena odoberie (stav `removed`), `POST /lists/{id}/members/unsubscribe` ho z tohto zoznamu odhlási. • Pridanie do zoznamu môže spustiť zapnutú automatizáciu so spúšťačom `list_added`. ## Segmenty {#segmenty} Segment patrí jednému e-shopu a vyhodnocuje sa nad kontaktmi s týmto hlavným e-shopom. Definícia je strom skupín A (`all`) / ALEBO (`any`) a pravidiel: ```json title="Definícia segmentu" {"type": "group", "match": "all", "rules": [ {"type": "list", "operator": "in", "listId": "43"}, {"type": "group", "match": "any", "rules": [ {"type": "order_value", "operator": "gte", "amount": "3000", "currency": "CZK", "shopId": "15", "days": "365"}, {"type": "field", "field": "lastClickAt", "operator": "in_last_days", "value": "30"}]}]} ``` • Najviac 8 úrovní skupín a 50 pravidiel. Prázdna podskupina je chyba; prázdny koreň zodpovedá všetkým kontaktom e-shopu (uložiť však ide len segment s aspoň jedným pravidlom). • **Hodnoty pravidiel sú reťazce**: počet dní `"30"` (1 až 3 650), suma `"1500.50"`, dátum `"2026-09-30"`. • Dni sú kalendárne dni v časovej zóne firmy: „za posledných 30 dní“ = od dnes minus 30 dní vrátane dneška; „nie za posledných N dní“ platí aj pre prázdny dátum (nikdy neotvoril). • Objednávky sa počítajú len dokončené; `order_value` sčíta len jednu menu (`currency` je povinná). • `refresh`: `daily` (vyhodnocuje sa živo) alebo `static` (snímka členov pri každom uložení). Typy pravidiel: `field` (pole kontaktu), `list` (členstvo), `order_count`, `order_value`, `last_order`, `order_attribute` (kód, kategória alebo značka v objednávke), `engagement` (A až E, N), `purpose` (platný súhlas), `custom_field`, `campaign` (doručené, otvorené, kliknuté), `segment` (člen iného segmentu). Všetky polia a operátory: [Referencia automatizácií › Pravidlá segmentov](https://www.postarna.sk/docs/api/automation-reference#pravidla-segmentu). ### Živý náhľad počtu `POST /segments/preview` spočíta kontakty bez uloženia: `matched` (spĺňa podmienky), `mailable` (z nich tí, ktorým možno písať), `total` (všetky kontakty e-shopu). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/segments/preview" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments/preview" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "shopId": "15", "definition": { "type": "group", "match": "all", "rules": [ { "type": "list", "operator": "in", "listId": "43" }, { "type": "group", "match": "any", "rules": [ { "type": "order_value", "operator": "gte", "amount": "3000", "currency": "CZK", "shopId": "15", "days": "365" }, { "type": "field", "field": "lastClickAt", "operator": "in_last_days", "value": "30" } ] } ] } } JSON ``` ```json title="Odpoveď: 200 OK" { "matched": 0, "mailable": 0, "total": 0 } ``` ### Uloženie ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/segments" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Aktivní a utrácející", "shopId": "15", "refresh": "daily", "definition": { "type": "group", "match": "all", "rules": [ { "type": "list", "operator": "in", "listId": "43" }, { "type": "group", "match": "any", "rules": [ { "type": "order_value", "operator": "gte", "amount": "3000", "currency": "CZK", "shopId": "15", "days": "365" }, { "type": "field", "field": "lastClickAt", "operator": "in_last_days", "value": "30" } ] } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "31", "name": "Aktivní a utrácející", "publicName": "", "shopId": "15", "refresh": "daily", "matched": 0, "mailable": 0, "computedAt": "2026-10-01T08:00:00.000Z", "ruleCount": 3, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "definition": { "type": "group", "match": "all", "rules": [ { "type": "list", "listId": "43", "operator": "in" }, { "type": "group", "match": "any", "rules": [ { "days": "365", "type": "order_value", "amount": "3000", "shopId": "15", "currency": "CZK", "operator": "gte" }, { "type": "field", "field": "lastClickAt", "value": "30", "operator": "in_last_days" } ] } ] }, "signatureHtml": "" } ``` Chybné pravidlo vráti 400 s cestou k poľu: `definition..`. Tu mena nepatrí e-shopu: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/segments" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Chybný", "shopId": "15", "refresh": "daily", "definition": { "type": "group", "match": "all", "rules": [ { "type": "order_value", "operator": "gte", "amount": "3000", "currency": "EUR", "shopId": "15" } ] } } JSON ``` ```json title="Odpoveď: 400 Bad Request" { "error": { "code": "validation", "message": "definition.0.currency" } } ``` • Odkazy medzi segmentmi (`segment`) smú viesť len na segment rovnakého e-shopu, nesmú vytvoriť cyklus ani reťazec dlhší než 5 (`definition.segmentCycle`, `definition.segmentDepth`). • E-shop uloženého segmentu sa nemení (400 `shop`). Názov je vo firme jedinečný (409 `name`). --- # Šablóny a personalizácia ## Šablóna a jej obsah Šablóna (`template`) má názov, predmet, preheader a obsah. Obsah je `{editor, html, design, version}`: • `editor: "html"`: obsah je HTML, `design` je `null`. Pre API najjednoduchšie. • `editor: "visual"`: obsah vizuálneho editora (MJML) v `design` (`{"format": "mjml-1", "mjml", "styles"}`) a z neho vykreslené `html`. Založenie so skopírovaným obsahom jedným volaním: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Opuštěný košík", "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku", "preheader": "Váš košík na vás počká ještě pár dní", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.

Dokončit objednávku

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "301", "name": "Opuštěný košík", "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku", "preheader": "Váš košík na vás počká ještě pár dní", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 465, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [ "subject_long" ], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.

Dokončit objednávku

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/1/72cf576a-85b2-474e-86e2-bfdbd1f4d38f" } ``` Úprava obsahu: `PUT /templates/{id}/content` s `{editor, html, design, baseVersion}`; `baseVersion` je verzia, ktorú ste načítali (pri novej šablóne 1). Iná verzia na serveri = 409 `conflict` / `version` s `params.current`. Každé uloženie sa zapíše do historie (`GET /templates/{id}/versions`). • HTML server pred uložením vyčistí: žiadne skripty, rámy, atribúty `on*`, odkazy `javascript:` ani nebezpečné CSS. Čistý vstup zostane bez zmeny. • HTML nad 102 000 bajtov hlási kontrola obsahu ako chybu a taký e-mail neodíde (Gmail dlhší e-mail oreže). • Kampaň má **vlastnú kópiu** obsahu (`PUT /campaigns/{id}/content`); neskoršia úprava šablóny kampaň nezmení. ### Šablóna, ktorú posiela zapnutá automatizácia Aby sa omylom nezmenil e-mail, ktorý práve chodí zákazníkom, uloží sa zmena obsahu takej šablóny do **konceptu**. E-maily posielajú ďalej publikovanú podobu, dokým koncept nepublikujete: • `POST /templates/{id}/publish` s `{"confirm": ""}` (API kľúčom; prihlásený človek posiela heslo). • `DELETE /templates/{id}/draft` koncept zahodí. • Zmazať šablónu, ktorú posiela zapnutá automatizácia, nejde (409 `conflict` / `in_use`). ## Kontrola obsahu `POST /content/lint` s `{html, subject, preheader}` vráti `issues` s kódmi (chyby prvé). Rovnaká kontrola beží pri schválení kampane a zapnutí automatizácie: **chyba** odoslanie zastaví, **upozornenie** nie. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/content/lint" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/content/lint" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "html": "

Dobrý den, {{df_jmeno}}

", "subject": "Podzimní novinky", "preheader": "" } JSON ``` ```json title="Odpoveď: 200 OK" { "issues": [ { "code": "unknown_tag", "severity": "error", "params": { "tags": "{{df_jmeno}}" } }, { "code": "no_unsubscribe", "severity": "warning", "params": {} } ] } ``` | Kód | Závažnosť | Kedy | |---|---|---| | `subject_missing` | chyba | prázdny predmet | | `subject_too_long` | chyba | predmet nad 200 znakov | | `content_empty` | chyba | žiadny text ani obrázok | | `unknown_tag` | chyba | neznáma zástupná značka (`params.tags`) | | `foreign_tag` | chyba | značky iných nástrojov (`*\|X\|*`, `%%x%%`, `{$x}`) | | `script_error` | chyba | skript Twig sa nedá spustiť (`params.line`, `params.detail`) | | `unsupported_filter` | chyba | nepodporovaný filter (napríklad `\|raw`) | | `bad_fallback` | chyba | neplatná náhrada `default(...)` | | `emoji` | chyba | emoji, keď ho firma zakázala | | `forbidden_word` | podľa pravidla | zakázané slovo podľa pravidiel firmy | | `image_placeholder`, `image_data_uri` | chyba | nenahradený zástupný obrázok, obrázok vložený ako `data:` | | `banned_host` | chyba | odkaz alebo obrázok na zakázanom hostiteľovi | | `html_too_large` | chyba | HTML nad 102 000 B | | `no_unsubscribe` | upozornenie | chýba `{{unsubscribe}}`; Poštárna doplní štandardnú pätičku | | `footer_incomplete` | upozornenie | odhlásenie nie je odkaz alebo chýba meno odosielateľa; doplní sa pätička | | `subject_long`, `img_without_alt`, `insecure_image`, `image_foreign_host`, `text_image_ratio` | upozornenie | odporúčanie | > **Odhlasovací odkaz:** každý obchodný e-mail musí obsahovať odkaz na odhlásenie. Keď v obsahu `{{unsubscribe}}` chýba, Poštárna doplní štandardnú pätičku s odkazom a identitou odosielateľa sama. ## Zástupné značky | Značka | Hodnota | |---|---| | `{{df_name}}`, `{{df_surname}}` | krstné meno, priezvisko | | `{{df_salution}}` | oslovenie v 5. páde („Petre“) | | `{{df_emailaddress}}` | e-mail príjemcu | | `{{df_titlesbefore}}`, `{{df_titlesafter}}`, `{{df_gender}}`, `{{df_birthday}}`, `{{df_nameday}}`, `{{df_language}}`, `{{df_company}}`, `{{df_street}}`, `{{df_town}}`, `{{df_postalcode}}`, `{{df_country}}`, `{{df_phone}}`, `{{df_cellphone}}`, `{{df_notes}}` | ďalšie polia kontaktu | | `{{df_id}}`, `{{df_created}}`, `{{df_updated}}`, `{{df_domain}}` | ID kontaktu, založenie, posledná zmena, doména adresy | | `{{cf_}}` | vlastné pole podľa ID (viac hodnôt oddelených čiarkou) | | `{{cl_sendername}}`, `{{cl_senderemail}}` | meno a e-mail odosielateľa | | `{{cl_company}}`, `{{cl_address}}` | firma a adresa odosielajúceho e-shopu | | `{{unsubscribe}}` (`{{unsubscribelink}}`) | odkaz na odhlásenie jedným kliknutím | | `{{preferences}}` (`{{confirmlink}}`) | odkaz na nastavenie odberu | | `{{webversion}}` (`{{webversionlink}}`, `{{forwardLink}}`) | webová verzia e-mailu | | `{{coupon_}}` | nový kód zo zásobníka kupónov s týmto kľúčom | **Náhrada prázdnej hodnoty**: `{{df_name|default('zákazníkovi', true)}}`. Text náhrady má 1 až 40 znakov a nesmie obsahovať `' " \ { } < > | % &`. V testovacom e-maile sa doplní meno „Test“ a odkazy na odhlásenie vedú na ukázkovú stránku, takže test nikoho neodhlási. ## Skripty (Twig) Obsah smie obsahovať bezpečnú podmnožinu jazyka Twig, rovnako ako SmartEmailing: `{% if %}`, `{% elseif %}`, `{% else %}`, `{% for %}` (aj `loop`), `{% set %}`, komentáre `{# #}`, operátory `and`, `or`, `not`, `in`, `~`, `??`, `? :`, testy (`is defined`, `empty`, `null`, `even`, `odd`, `divisible by`), filtre (`abs`, `capitalize`, `date`, `default`, `first`, `join`, `json_encode`, `keys`, `last`, `length`, `lower`, `merge`, `number_format`, `replace`, `reverse`, `round`, `slice`, `sort`, `split`, `striptags`, `title`, `trim`, `upper`, `url_encode`) a funkcie `date()`, `min()`, `max()`. Každá vypísaná hodnota sa escapuje, filter `raw` nie je k dispozícii. Dáta pre skripty: | Výraz | Čo vráti | |---|---| | `data.orders(filter, triedenie, limit)` | objednávky kontaktu v e-shope e-mailu (najviac 200 najnovších); položky `items[]` | | `data.products({'item_id': kód}, triedenie, limit)` | produkty produktových feedov e-shopu | | `data.articles(filter, triedenie, limit)` | články článkových feedov (najviac 25) | | `data.lists(filter)` | zoznamy kontaktu a ich stavy | | `data.promoCode('')` | nový kód kupónu zo zásobníka s týmto **názvom** pre každý e-mail | | `data.promo.assigned('', od, do)` | kódy, ktoré kontakt už dostal | | `data.terminate('')` | e-mail tomuto kontaktu neodošle (preskočí sa) | | `metadata.order` | objednávka, ktorá spustila beh automatizácie (len v e-maile automatizácie) | | `metadata.event.attributes` | dáta udalosti, ktorá beh spustila (košík: `itemCount`, `total`, `currency`, `shopId`; vlastná udalosť: `name` a `data`; návšteva: `url`, `visitType`, `attributes`) | ```twig title="Ukázka skriptu v obsahu" {% set o = metadata.order %} {% if o %}

Ďakujeme za objednávku {{ o.eshop_code }}.

    {% for item in o.items %}
  • {{ item.name }}
    • {% endfor %}
{% endif %}

Váš kód: {{ data.promoCode('Svátek') }}

``` • Kupón: `{{ data.promoCode('Svátek') }}` berie **názov** zásobníka, `{{coupon_svatek}}` jeho **kľúč** (`mergeKey`). Keď zásobník dojde, e-mail neodíde a automatizácia zaznamená zlyhanie `customizationDataboxOutOfPromocodes`. • Skript, ktorý sa nedá spustiť, zastaví e-mail (`failed`); kontrola obsahu ho nájde skôr ako `script_error`. • **Nepodporované**: zoznam položiek košíka v e-maile (v dátach košíka je len počet kusov a súčet), všeobecné feedy (`data.generic.items` vracia prázdny zoznam). ## Testovací e-mail • Ide len na testovacie adresy firmy (`GET /test-recipients`); iná adresa = 400 `validation` / `to`. • `POST /campaigns/{id}/test` s `{"to"}`, `POST /templates/{id}/test` s `{"shopId", "to"}`. Predmet dostane predponu `[TEST] `, nič sa nemeria. • Najviac 10 testov jednej kampane alebo šablóny za 24 hodín (429 `rate_limited` / `test`). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/test" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/test" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "to": "test@example.cz" } JSON ``` ```json title="Odpoveď: 200 OK" { "to": "test@example.cz", "sentAt": "2026-10-01T08:00:00.000Z" } ``` ## Pätičky, odhlasovacie stránky a ďalší obsah • Pätičky (`/footers`) a odhlasovacie stránky (`/unsubscribe-pages`) majú východiskovú položku firmy; šablóna a uzol automatizácie môžu mať vlastné. • Šablóny skriptov (`/script-templates`), uložené prvky editora (`/editor-elements`), správca súborov (`/files`, `/file-folders`), landing pages, dotazníky a šablóny SMS majú vlastné skupiny v [referencii](https://www.postarna.sk/docs/api/reference-templates). --- # Kampane Kampaň je jednorazová rozosielka (newsletter) jedného e-shopu. **Nič neodíde z konceptu**: odoslanie spustí len schválenie s potvrdeným počtom príjemcov. ## Stavy | Akcia | Zo stavu | Do stavu | |---|---|---| | `POST /campaigns/{id}/approve` so `sendAt` | `draft` | `scheduled` | | `POST /campaigns/{id}/approve` so `sendAt: null` | `draft` | `sending` | | nastal čas odoslania | `scheduled` | `sending` (alebo `paused` s `recipient_drift`, keď sa počet príjemcov zmenil o viac než 5 %) | | automatická pauza | `sending` | `paused` (`bounce_rate`, `complaint_rate`, `unsubscribe_rate`, `template_error`) | | `POST /campaigns/{id}/pause` | `scheduled`, `sending` | `paused` (`manual`) | | `POST /campaigns/{id}/resume` | `paused` | `sending`, alebo `scheduled`, keď ešte nezačala | | `POST /campaigns/{id}/cancel` | `draft`, `scheduled`, `sending`, `paused` | `cancelled` | | odišiel posledný e-mail | `sending` | `completed` | Iný prechod = 409 `conflict` / `status`. Upravovať (`PATCH`, obsah) ide len koncept. ## Koncept `POST /campaigns` založí koncept; povinné sú len `name` a `shopId`, zvyšok doplníte neskôr. • `senderId`: overený odosielateľ e-shopu kampane (`GET /senders`). • `fromName`, `subject` (do 200 znakov), `preheader`. • `audience`: komu kampaň ide (pozrite nižšie). • `trackOpens`, `trackClicks` (východiskovo `true`), `utm` (`{source, medium, campaign, term?, content?}` alebo `null`), `linkParams`, `headers` (vlastné hlavičky `X-...`). • `templateId` je len informácia, odkiaľ sa obsah skopíroval. Obsah kampane uložíte cez `PUT /campaigns/{id}/content` (`{editor, html, design, baseVersion}`, pri novej kampani `baseVersion: 0`). ## Publikum ```json title="audience" {"listIds": ["42"], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": []} ``` • `listIds`, `segmentIds`: zoznamy e-shopu kampane alebo celej firmy a segmenty e-shopu kampane (najviac 100 ID v každom poli). • `excludeListIds`, `excludeEmails` (najviac 1 000 adries): vylúčenie. • `excludeInactive`: vynechá kontakty s angažovanosťou E. • `onlyWithPurpose` a `purposeIds`: len kontakty s platným súhlasom pre niektorý z účelov. `POST /campaigns/audience` spočíta príjemcov a dôvody vylúčenia (každý kontakt má jeden dôvod): `not_mailable` (odhlásený, nedoručiteľný, sťažnosť, potlačený), `unconfirmed`, `weak_consent`, `exception_expired`, `no_purpose`, `excluded_list`, `excluded_manual`, `inactive`. Platí `recipients + súčet excluded = matched`. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/audience" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/audience" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "shopId": "17", "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] } } JSON ``` ```json title="Odpoveď: 200 OK" { "matched": 1, "recipients": 1, "excluded": { "not_mailable": 0, "unconfirmed": 0, "weak_consent": 0, "exception_expired": 0, "no_purpose": 0, "excluded_list": 0, "excluded_manual": 0, "inactive": 0 } } ``` ## Schválenie (odoslanie) `POST /campaigns/{id}/approve` s `{"sendAt", "expectedRecipients"}`: • `sendAt`: `null` = odoslať hned, inak čas 5 minút až 365 dní dopredu (ISO 8601 so zónou). • `expectedRecipients`: počet príjemcov, ktorý ste práve spočítali a užívateľ potvrdil. Keď sa skutočný počet líši o viac než 5 %, server vráti 409 `conflict` / `recipients` s `params.expected` a `params.actual` a kampaň zostane konceptom: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/approve" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/approve" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "sendAt": "2026-10-02T07:00:00.000Z", "expectedRecipients": 250 } JSON ``` ```json title="Odpoveď: 409 Conflict" { "error": { "code": "conflict", "message": "recipients", "params": { "expected": 250, "actual": 1 } } } ``` Kontroly v tomto poradí: stav `draft`, `subject`, `fromName`, `senderId` (overený odosielateľ rovnakého e-shopu), `content` (bez obsahu nejde odoslať), `lint` (chyba kontroly obsahu, `params.codes`), `audience` (aspoň jeden zoznam alebo segment a aspoň jeden príjemca), `sendAt`, `expectedRecipients`. > **Pozor:** schválenie posiela e-maily skutočným ľuďom a nejde vrátiť späť. Integrácia aj AI agent majú pred schválením ukázať človeku predmet, odosielateľa, čas a počet príjemcov a nechať si ho potvrdiť. ## Čo musí byť nastavené, aby e-maily odišli • Overený odosielateľ e-shopu (doména s SPF, DKIM a DMARC, Nastavenia › Odosielanie; cez API `/sending/...`). • Zapnuté odosielanie firmy: `GET /sending-mode` vracia `sendingEnabled` (hlavný vypínač firmy, zapína ho len prihlásený človek) a `sendingState` (schválenie ostrého odosielania platformou). Dokým je vypnuté, naplánované kampane čakajú a automatizácia nikoho nepustí; testovacie e-maily chodia. • Denné limity a zahrievanie novej domény rozložia veľké rozosielky v čase. ## Štatistiky {#statistiky} `GET /campaigns/{id}` vracia `stats` (`sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `unsubscribed`; unikátne kontakty, `delivered + bounced = sent`). Podrobne: `GET /stats/campaigns/{id}`, `/activity`, `/conversions`, `/recipients` (aj CSV), `/heatmap` v skupine [Štatistiky](https://www.postarna.sk/docs/api/reference-statistics). Strojové otvorenia a kliky (skenery odkazov) sa nepočítajú. ## Jazykové varianty Kampaň môže mať jazykové varianty pre kontakty s iným jazykom (`/campaigns/{id}/variants`): náhľad rozdelenia (`/variants/preview`), schválenie (`/variants/approve`), pauza, obnovenie a zrušenie celej skupiny. API kľúčom sa dajú volať; AI asistent cez MCP skupinu variant neschváli (posiela ju len človek v aplikácii). --- # Automatizácie Automatizácia (scenár) je **graf**: uzly (spúšťače, operátory, akcie) spojené hranami. Kontakt do scenára vstúpi spúšťačom, prechádza uzlami po hranách a scenár opustí v uzle Konec, na výstupe bez hrany alebo splnením cieľa. Každý priechod jedného kontaktu je **beh** (`run`). Presné schémy všetkých uzlov, udalostí, podmienok a časových údajov: [Referencia automatizácií](https://www.postarna.sk/docs/api/automation-reference). Hotové scenáre: [recepty](https://www.postarna.sk/docs/api/recipe-abandoned-cart). ## Graf ```json title="AutomationGraph" { "nodes": [ {"id": "kosik", "type": "trigger_event", "name": "Zmena košíka", "config": {"event": "cart_updated", "reentry": "restart"}}, {"id": "pockat", "type": "wait", "config": {"mode": "duration", "value": 2, "unit": "hours"}}, {"id": "stale-v-kosiku", "type": "condition", "config": {"definition": {"type": "group", "match": "all", "rules": [ {"type": "cart_items_count", "operator": "gt", "value": 0}, {"type": "ordered_since_entry", "operator": "no"}]}}}, {"id": "email", "type": "send_email", "config": {"templateId": "301"}} ], "edges": [ {"source": "kosik", "target": "pockat", "branch": "next"}, {"source": "pockat", "target": "stale-v-kosiku", "branch": "next"}, {"source": "stale-v-kosiku", "target": "email", "branch": "yes"} ] } ``` • `id` uzla je **kľúč**, ktorý si zvolíte: písmená, číslice, `-` a `_`, najviac 40 znakov, v grafe jedinečný. Pri ďalších uloženiach ho nechajte rovnaký: behy, história a e-maily sa na uzol odkazujú kľúčom. • `type` vyberá druh uzla, `config` jeho nastavenie. Neznáme kľúče v `config` server pri uložení zahodí. Voliteľne `name` (do 100 znakov), `note` (do 1 000) a `position` `{x, y}` pre plátno v aplikácii. • Hrana vedie z **výstupu** (`branch`) zdroja do cieľa: `next` (jediný výstup), `yes` / `no` (podmienka), `v1` až `v10` (A/B test). Každý výstup má najviac jednu hranu; výstup bez hrany = kontakt scenár opustí. • Graf nesmie mať cyklus (ani cez uzol `goto`), do spúšťača a cieľa nevedie hrana. Scenár smie mať **viac spúšťačov**. Najviac 300 uzlov a 600 hrán. • Automatizácia patrí jednému e-shopu (odosielateľ, pätička, objednávky spúšťačov); e-shop sa po založení nemení. ## Druhy uzlov | Skupina | Typy | |---|---| | Spúšťače | `trigger_event` (udalosť), `trigger_date` (meniny, narodeniny, dátum, výročia v roku, prvá objednávka), `trigger_reorder` (kúpte si znovu), `trigger_repeat` (opakovane), `trigger_scheduled` (jednorazovo v čase), `trigger_now` (jednorazovo pri zapnutí) | | Operátory | `condition` (áno / nie), `wait` (čakanie), `ab_test`, `holding` (odkladisko), `goal` (cieľ scenára) | | Akcie | `send_email`, `list_change`, `set_field`, `webhook`, `fire_event`, `notify`, `reset`, `goto`, `end` | | Zatiaľ nedostupné | `send_sms`, `send_viber`, `whatsapp`, `fb_audience`, `sklik_retargeting`, `motionlab_adina` (uložiť sa nedajú, chyba `unavailable`) | ### Spúšťač pri udalosti (`trigger_event`) `config.event` vyberá udalosť; niektoré majú vlastné nastavenie: | Udalosť | Kedy | Nastavenie | |---|---|---| | `order_created` | nová objednávka | `shopId` | | `order_completed` | objednávka dokončená (zaplatená, odoslaná, doručená) | `shopId` | | `order_changed` | objednávka zmenila stav | `shopId`, `state` | | `cart_updated` | zmena košíka (`POST /contact-events` typ `cart`) | `shopId` | | `page_visit` | návšteva stránky (`POST /contact-events` typ `visit`) | `shopId`, `url`, `urlOperator`, `visitType` | | `custom` | vlastná udalosť (`POST /contact-events` typ `custom`, alebo uzol `fire_event` iného scenára) | `customEvent` | | `subscribed` | kontakt sa prihlásil na odber | `sources` | | `contact_created` | nový kontakt | | | `contact_updated` | zmena poľa kontaktu | `fieldFilter` | | `list_added` | pridanie do zoznamu | `listId` | | `list_status_changed` | zmena stavu v zozname | `listId`, `status` | | `form_submitted` | odoslaný a potvrdený formulár | `formId` | | `email_sent`, `link_clicked` | e-mail alebo klik z uzla **iného** scenára | `emailNode`, `link`, `compareParams` | | `engagement_changed` | zmena angažovanosti | | | `blacklisted` | kontakt na blacklistu | | | `action_failed` | zlyhala akcia automatizácie | `failureType`, `failureNode` | | `manual` | ručne pridané kontakty (`POST /automations/{id}/contacts`) | | Počítajú sa len udalosti **po zapnutí** automatizácie. Čo zapísal hromadný zápis (import, synchronizácia e-shopu), automatizácia nespustí, pokiaľ import výslovne nepovolí `runAutomations: true`. Objednávka zapísaná cez `POST /orders` spúšťače objednávok spúšťa. ### Opakovaný vstup (`reentry`) Každý spúšťač má `reentry`: • `parallel`: kontakt smie mať v scenári viac behov súčasne (najviac 10); východiskové pre nové spúšťače. • `restart`: nový vstup ukončí rozbehnutý beh (typicky košík). • `skip`: dokým beh kontaktu trvá, znovu nevstúpi. • `once`: raz a navždy. ## Jazyk podmienok Uzol `condition`, cieľ (`goal`) a filter časových spúšťačov (`filter`) majú **definíciu**: rovnaký strom ako [segment](https://www.postarna.sk/docs/api/lists-and-segments#segmenty), ktorého pravidlá smú byť aj podmienky automatizácie. ```json title="definition" {"type": "group", "match": "all", "rules": [ {"type": "contact_in_list", "listId": "41", "state": "confirmed"}, {"type": "orders_total_value", "operator": "gte", "value": "3000", "currency": "CZK", "period": {"from": {"variant": "interval", "sign": "-", "value": 1, "unit": "years"}, "to": null}}, {"type": "email_activity", "operator": "opened", "nodeId": "email-1", "negate": true} ]} ``` • `match`: `all` (a zároveň) alebo `any` (alebo). Skupiny sa môžu vnárať (najviac 8 úrovní, 50 pravidiel). • Každé pravidlo smie mať `"negate": true` (neplatí, že). • Pravidlá s obdobím majú `period` `{from, to}`; strany sú [časové údaje](https://www.postarna.sk/docs/api/automation-reference#casove-udaje) relatívne k teraz, `null` = bez obmedzenia. • Podmienky automatizácií (37 podľa SmartEmailingu a vlastné): kontakt v zozname, v automatizácii, pole kontaktu, výročie (narodeniny, meniny), odoslané a otvorené e-maily, počet a hodnota objednávok, objednaný produkt alebo atribút, košík, deň v mesiaci a týždni, hodina, kupón, skript, kliky, návštevy, feed, víťaz A/B testu, angažovanosť. • Pravidlá, ktoré čítajú beh (`email_activity`, `passed_node`, `ordered_since_entry`, `event_attribute`, `script`), nejde použiť vo filtri spúšťača (beh tam ešte nie je). • Hodnoty podmienok automatizácií smú byť čísla (`"value": 0`) aj reťazce číslic; pravidlá segmentu majú hodnoty ako reťazce. Presné polia každého pravidla: [Referencia automatizácií](https://www.postarna.sk/docs/api/automation-reference#podminky-automatizaci). ### Podmienka s čakaním na splnenie `condition.config.waitUntilMet` `{"value": 3, "unit": "days"}`: kontakt v uzle čaká, dokým podmienka neplatí (potom výstup `yes`), najdlhšie po zadanú dobu (potom `no`). Kontrola beží každých 20 minút až raz denne podľa dĺžky čakania. ## Čakanie a čas Uzol `wait` má `mode`: | `mode` | Čaká | |---|---| | `duration` | `value` jednotiek `unit` (minúty až roky) | | `time_of_day` | na najbližší `time` (`"09:00"`) | | `weekday` | na najbližší deň z `weekdays` (1 = pondelok) v čase `time` | | `date` | na miestny dátum a čas `date` (`"2026-12-24T09:00"`) | | `time` | na časový údaj `spec` (`countFrom` `node` = od príchodu do uzla, `scenario` = od vstupu do scenára) | | `preferred` | na obvyklý čas, kedy kontakt otvára e-maily (bez historie nečaká) | | `spread` | rozloží kontakty rovnomerne do obdobia `spread` | Najdlhšie čakanie je 10 rokov. Časové údaje (`spec`, `period`) majú tri varianty: `calendar` (konkrétny deň), `interval` (posun o jednotky), `event` (pomenovaný deň: zajtra, ďalší pondelok, ďalší pracovný deň, posledný deň mesiaca). Náhľad presného okamihu: `POST /automations/resolve-time`. ## Životný cyklus | Stav | Význam | |---|---| | `draft` | koncept, nikdy nespustený | | `active` | beží | | `paused` | zastavený po behu (ručne, alebo automaticky pri vysokom podiele nedoručiteľných, sťažností či odhlásení, alebo pri chybe šablóny; `pausedReason`) | • `POST /automations` založí koncept (verzia 1); graf môžete poslať rovno, alebo neskôr cez `PUT /automations/{id}/graph`. • `POST /automations/{id}/activate` zapne: `draft` alebo `paused` → `active`. Keď niečo chýba, vráti 400 `validation` / `graph` s `params.issues` (pozrite nižšie). Zapnutie posiela e-maily skutočným ľuďom. • `POST /automations/{id}/pause` zastaví; čakajúce kontakty zostanú na mieste a po ďalšom zapnutí pokračujú. • `DELETE /automations/{id}` zmaže len scenár, do ktorého nikto nevstúpil (inak 409 `runs`). • `POST /automations/{id}/copy` vytvorí koncept „ - kópia“ (bez hesiel webhookov). ## Validácia a problémy grafu {#validace-a-problemy-grafu} Problémy majú tvar `{"node": "" | null, "field": "", "code": ""}` a dve úrovne: • **Chyby** (`errors`): graf sa nedá uložiť (400 `validation` / `graph` s `params.issues`). Kódy: `invalid`, `unavailable` (typ uzla), `duplicate`, `node` (hrana k neexistujúcemu uzlu), `cycle`, `self_trigger` (scenár by spúšťal sám seba). • **Neúplné nastavenie** (`incomplete`): graf sa uloží, ale nejde zapnúť ani otestovať. Kódy: `required`, `invalid`, `unavailable` (udalosť alebo podmienka), `not_found`, `locked` (zoznam napojený na e-shop), `empty` (šablóna bez obsahu), `lint` (chyba kontroly obsahu šablóny), `unverified` (neoverený odosielateľ), `unreachable` (uzol, kam žiadny spúšťač nedojde), `too_short`, `too_long`, `not_whitelisted`, `reserved`. Bez spúšťača: `{"node": null, "field": "trigger", "code": "required"}`. `POST /automations/validate` s `{shopId, graph}` skontroluje graf bez uloženia: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/validate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/validate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "shopId": "1", "graph": { "nodes": [ { "id": "kosik", "type": "trigger_event", "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } }, { "id": "pockat", "type": "wait", "config": { "mode": "duration", "value": 2, "unit": "hours" } }, { "id": "email", "type": "send_email", "config": {} } ], "edges": [ { "source": "kosik", "target": "pockat" }, { "source": "pockat", "target": "email" } ] } } JSON ``` ```json title="Odpoveď: 200 OK" { "errors": [], "incomplete": [ { "node": "email", "field": "templateId", "code": "required" } ] } ``` Detail automatizácie (`GET /automations/{id}`) vracia v `issues` všetko, čo bráni zapnutiu. ## Uloženie grafu a verzie `PUT /automations/{id}/graph` s `{"baseVersion", "graph"}` vráti detail s verziou + 1. • Iná verzia na serveri = 409 `conflict` / `version` s `params.current`. • **Bežiaci scenár** (`active`) sa uloží len s `"confirmRunning": true` a len bez akéhokoľvek problému; inak 409 `conflict` / `confirm`. Zmeny platia pre ďalší krok každého kontaktu. • Odstrániť alebo zmeniť typ uzla, v ktorom kontakty čakajú, nejde: 409 `conflict` / `waiting` s `params.nodes` (najprv ich uvoľnite: `POST /automations/{id}/nodes/{kľúč}/release`). • Zmena spúšťača začne jeho plán znovu; nová hrana z odkladiska pustí čakajúce kontakty ďalej. • Každé uloženie je verzia: `GET /automations/{id}/versions`, `GET /automations/{id}/versions/{verzia}`. ```bash title="Požiadavka: PUT /api/v1/tenants/{tenant}/automations/81/graph" curl -sS -X PUT "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/graph" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "baseVersion": 1, "graph": { "nodes": [], "edges": [] } } JSON ``` ```json title="Odpoveď: 409 Conflict" { "error": { "code": "conflict", "message": "confirm" } } ``` ## Testovanie a sledovanie • `POST /automations/{id}/test`: skúšobný priechod nad dnešnými dátami, **nič sa neuloží ani neodošle**. Vráti, koľko kontaktov by vstúpilo a koľko by ich došlo do každého uzla a výstupu. Voliteľne `graph` (neuložený graf z editora) a `days` (1 až 90, okno prehrania udalostí). • `POST /automations/{id}/trace` s `{"contactId" | "email"}`: priechod jedného kontaktu krok za krokom s dôvodmi (smie vstúpiť, kam pôjde, kde skončí). Nič sa neodošle. • `GET /automations/{id}/counts`: živé počty po uzloch a výstupoch vrátane čakajúcich. • `GET /automations/{id}/runs?contactId=`: história behov kontaktu. • `GET /automations/{id}/nodes/{kľúč}/passes`: kto prešiel uzlom. • `GET /automations/{id}/report?from=&to=` (aj `format=csv`): štatistiky e-mailových uzlov a volaní webhookov. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/83/test" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/83/test" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' {} JSON ``` ```json title="Odpoveď: 200 OK" { "scope": "today", "days": null, "since": null, "entered": 0, "waiting": 0, "left": 0, "nodes": { "svatek": { "reached": 0, "waiting": 0, "left": 0, "outputs": { "next": 0 } }, "prani": { "reached": 0, "waiting": 0, "left": 0, "outputs": { "next": 0 } } }, "testedAt": "2026-10-01T08:00:00.000Z" } ``` ## Kto vstúpi a kedy odíde e-mail • Vstupujú len kontakty, ktorým sa môže písať (prihlásené, bez potlačenia a slabého súhlasu, v lehote zákaznickej výnimky) z e-shopu automatizácie. • E-mail uzla odíde jednému kontaktu najviac raz za 24 hodín (nastavenie firmy) a len so zapnutým odosielaním firmy, v dennom limite. Pred odoslaním sa stav kontaktu kontroluje znovu; e-mail starší než 48 hodín v poradí neodíde. • Scenár, ktorý by spúšťal sám seba, sa nedá uložiť (`self_trigger`); reťaz scenárov (udalosť jedného spúšťa druhý) končí po 3 krokoch. • Beh spustený objednávkou skončí, keď sa objednávka zruší, vráti alebo zmaže. ## Udalosti z vášho systému `POST /contact-events` zapíše udalosť existujúceho kontaktu (podľa `contactId` alebo `email`; nikdy kontakt nezaloží): • `{"type": "custom", "name": "vip-dosiahnuty", "data": {...}}`: vlastná udalosť pre spúšťač `custom` (názov a-z, 0-9 a `-`, najviac 50 znakov, nie `se-`). • `{"type": "cart", "shopId", "items": [{code, name, quantity, price, url}], "currency", "total"}`: aktuálny stav košíka (prázdne `items` = košík vyprázdnený) pre `cart_updated` a podmienku `cart_items_count`. • `{"type": "visit", "shopId", "url", "visitType", "attributes"}`: návšteva stránky pre `page_visit`. Najviac 60 udalostí jedného kontaktu za 10 minút (429 `rate_limited`). Ukázka v [recepte opusteného košíka](https://www.postarna.sk/docs/api/recipe-abandoned-cart). ## Transakčné automatizácie (zmluvné e-maily) Na e-maily k uzavretej zmluve, napríklad upomienky splatnosti faktúr. Režim zapnete poľom `"transactional": true` pri `POST /automations` alebo `PATCH /automations/{id}` (rovnaké oprávnenie ako úprava automatizácií); prepnúť sa dá len scenár, ktorý nebeží (inak 409 `conflict` / `status`). • Spúšťač smie byť len vlastná udalosť (`trigger_event` s `event: "custom"`) a uzly len `send_email`, `wait`, `condition` a `end`. Iný graf vráti 400 `validation` / `transactional` (pri prepnutí) alebo `graph` (pri uložení) s `params.issues` a kódmi `transactional_node`, `transactional_trigger`. • E-mail dostane každý existujúci kontakt bez ohľadu na súhlas s newsletterom alebo odhlásenie z neho. Tvrdý odraz, sťažnosť, neplatná adresa, limit mäkkých odrazov a blacklist ho zastavia vždy, pri vstupe aj tesne pred odoslaním. • E-mail nemá odkaz na odhlásenie, hlavičku `List-Unsubscribe` ani pätičku newslettera. Šablóna preto nepotrebuje `{{unsubscribe}}` a nesmie ho mať (ani `{{gf_footer}}`, odkaz na nastavenie odberu alebo kupón; kód problému `transactional_content`). Otvorenia a prekliky sa merajú ako zvyčajne. • Scenár patrí e-shopu udalosti: `shopId` pri `POST /contact-events` určuje, ktorá automatizácia sa spustí (bez neho sa použije hlavný e-shop kontaktu). Limit jedného e-mailu uzla za 24 hodín neplatí (dve faktúry jednej firmy s rovnakou splatnosťou dostanú dva e-maily); váš systém stráži opakovanie. • Predmet e-mailu je obyčajný text bez skriptov: značky `{{metadata.event.attributes.data.}}` v ňom čítajú dáta udalosti (len jednoduché hodnoty), napríklad `Faktúra {{metadata.event.attributes.data.invoiceNumber}}`. • Platobný QR kód: značka `{{payment_qr}}` vloží obrázok QR platby z `data.spayd` udalosti (reťazec SPAYD 1.0 s účtom `ACC`, český štandard pre platby v CZK), napríklad `{% set d = metadata.event.attributes.data %}{% if d.spayd %}{{payment_qr}}{% endif %}`. Obrázok je podpísaný odkaz `/m/r/.png` na doméne odkazov, takže ho ukáže aj Gmail a Outlook; bez platného reťazca sa nevloží nič. • Právna poznámka (nie je právne stanovisko): upomienka k vystavenej faktúre nie je obchodné oznámenie (zákon 452/2021 Z. z., v Česku zákon 480/2004 Sb.), právnym základom je plnenie zmluvy. E-mail preto nesmie obsahovať marketing (ponuky tovaru, kupóny, bannery). --- # Referencia automatizácií Všetko na tejto stránke sa generuje z kódu validátora Poštárne a testy overujú, že každý príklad validátor prijme, že bez povinného poľa automatizácia nejde zapnúť a že výčtové hodnoty zodpovedajú validátoru. Rovnaké schémy sú v [OpenAPI](https://www.postarna.cz/api/openapi.json?tag=Automations) ako `AutomationNode_`, `ConditionRule_`, `SegmentRule_` a `TimeSpec`. Technické popisy polí sú po anglicky, rovnako ako v OpenAPI. ## Uzly Každý uzol: `{"id": "", "type": "", "name"?, "note"?, "position"?, "config": {...}}`. Pole so stĺpcom „Povinné“ = áno musí byť vyplnené, inak automatizácia nejde zapnúť ani otestovať (graf sa ale uloží, pozrite [validáciu](https://www.postarna.sk/docs/api/automations#validace-a-problemy-grafu)). Ďalšie polia bývajú povinné len pri niektorých hodnotách (napríklad `listId` pri udalosti `list_added`); popis to uvádza. ### Spúšťače #### `trigger_now` {#node-trigger-now} Starts once, right at the activation, with the contacts of the shop matching the filter (SmartEmailing "Hned teď"). **Výstupy:** `next` · SmartEmailing: `run` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `filter` | `ConditionGroup` or null | nie | Who may enter: a condition tree (segment rules and automation conditions except the run only ones). null or left out = every mailable contact of the shop. | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-now-1", "type": "trigger_now", "config": { "reentry": "once" } } ``` #### `trigger_scheduled` {#node-trigger-scheduled} Starts once at a local date and time (SmartEmailing "V plánovaný čas"). **Výstupy:** `next` · **Povinné na zapnutie:** `at` · SmartEmailing: `scheduled-time` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `at` | string | áno | YYYY-MM-DDTHH:MM, local time of the company. pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `filter` | `ConditionGroup` or null | nie | Who may enter: a condition tree (segment rules and automation conditions except the run only ones). null or left out = every mailable contact of the shop. | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-scheduled-1", "type": "trigger_scheduled", "config": { "at": "2026-12-01T09:00", "reentry": "once" } } ``` #### `trigger_repeat` {#node-trigger-repeat} Starts repeatedly every `every` from startAt (default the activation) until stopAt, with the contacts matching the filter (SmartEmailing "Opakovat"). **Výstupy:** `next` · **Povinné na zapnutie:** `every` · SmartEmailing: `repeat` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `every` | object | áno | Interval, at least 15 minutes, at most 10 years. | | `startAt` | string | nie | YYYY-MM-DDTHH:MM (local). pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `stopAt` | string | nie | YYYY-MM-DDTHH:MM (local), after startAt. pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `filter` | `ConditionGroup` or null | nie | Who may enter: a condition tree (segment rules and automation conditions except the run only ones). null or left out = every mailable contact of the shop. | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-repeat-1", "type": "trigger_repeat", "config": { "every": { "value": 1, "unit": "days" }, "startAt": "2026-11-01T08:00", "reentry": "parallel", "filter": { "type": "group", "match": "all", "rules": [ { "type": "contact_anniversary", "field": "nameDay", "relation": "now" } ] } } } ``` #### `trigger_event` {#node-trigger-event} Starts when an event happens to a contact (SmartEmailing "Při události"). Only events after the activation count. Event specific settings: `cart_updated`: The contact's cart changed (POST /contact-events type cart). shopId narrows the shop. `contact_created`: A new contact of the automation's shop. `order_created`: A new order (shopId: shop of the order, default the automation's shop). `order_changed`: An order changed state (state narrows to one state). `list_added`: The contact was added to listId. `contact_updated`: A profile field changed (fieldFilter narrows to one field and its values before / after). `action_failed`: An action of an automation failed (failureType, failureNode narrow it). `list_status_changed`: The contact's state in listId changed to status. `email_sent`: An e-mail of emailNode (a send_email node of ANOTHER automation) was sent. `page_visit`: A web tracking visit (POST /contact-events type visit): url, urlOperator, visitType. `link_clicked`: The contact clicked a link (link, compareParams) in an e-mail of emailNode (another automation). `engagement_changed`: The contact's engagement level changed. `custom`: A custom event named customEvent (POST /contact-events type custom, or a fire_event node of another automation). `form_submitted`: A form was submitted and confirmed (formId narrows to one form). `blacklisted`: The contact was blacklisted. `order_completed`: An order was completed (paid, shipped or delivered). `subscribed`: The contact subscribed (sources narrows the source; imports only when listed). `manual`: Contacts added by hand: POST /automations/{id}/contacts. **Výstupy:** `next` · **Povinné na zapnutie:** `event` · SmartEmailing: `on-event` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `event` | one of: `cart_updated`, `contact_created`, `order_created`, `order_changed`, `list_added`, `contact_updated`, `score_changed`, `action_failed`, `list_status_changed`, `automation_saved`, `email_sent`, `sms_sent`, `page_visit`, `motionlab_rendered`, `link_clicked`, `engagement_changed`, `custom`, `form_submitted`, `blacklisted`, `order_completed`, `subscribed`, `manual` | áno | The event. Not available yet: score_changed (scoring), automation_saved (unverified), sms_sent (sms), motionlab_rendered (motionlab). | | `shopId` | string | nie | Orders, carts, visits: shop (default the automation's). | | `listId` | string | nie | list_added, list_status_changed: list id. | | `sources` | array of one of: `erp_order`, `signup_form`, `import`, `api`, `manual`, `shoptet`, `smartemailing` | nie | subscribed: sources (default erp_order, signup_form, api, manual). min 1 items | | `state` | one of: `new`, `unpaid`, `paid`, `processing`, `shipped`, `pickup`, `delivered`, `cancelled`, `returned`, `other` | nie | order_changed: the new order state. | | `status` | one of: `confirmed`, `unsubscribed`, `removed` | nie | list_status_changed: the new state. | | `fieldFilter` | object | nie | contact_updated: one field and optionally its values before and after. Operators by field kind: text: any, eq, empty, filled, contains, starts; date: any, on_day, newer, until, older, from, filled, empty; number: any, gt, gte, lt, lte, filled, empty; choice: any, eq_option, filled, empty; multi: any, has_option, filled, empty; checkbox: any, checked, unchecked. Fields: affiliateId, language, firstName, mobile, city, birthday, vocativeFirstName, salutation, salutationFormal, vocativeLastName, gender, note, lastName, postalCode, company, nameDay, phone, titleBefore, titleAfter, street, country or cf:. | | `failureType` | one of: `customizationDataboxTerminate`, `customizationDataboxOutOfPromocodes`, `customizationSyntaxError`, `contactSetFieldFail`, `smsRateLimitReached`, `sklikError`, `other` | nie | action_failed: type. | | `failureNode` | object | nie | action_failed: the node (automationId null = this graph). | | `emailNode` | object | nie | An e-mail node: automationId null (or left out) = a send_email node of this graph, else the id of another automation of the company and its node key. | | `link` | string | nie | link_clicked: the URL (at most 2 000); empty = any link. | | `compareParams` | boolean | nie | link_clicked: compare query parameters, default true. | | `url` | string | nie | page_visit: URL (at most 2 000). | | `urlOperator` | one of: `eq`, `starts` | nie | page_visit: eq (default) or starts. | | `visitType` | one of: `home`, `article`, `cart`, `product`, `category`, `search`, `order_done`, `other` | nie | page_visit: type of page. | | `customEvent` | string | nie | custom: event name, a-z, 0-9 and - (1 to 50), not starting with se-. pattern `^[a-z0-9-]{1,50}$` | | `formId` | string | nie | form_submitted: form id (empty = any form). | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-event-1", "type": "trigger_event", "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } } ``` #### `trigger_date` {#node-trigger-date} Starts once a day at `at` for contacts whose date is today: name day, birthday, a date custom field (shifted by offsetDays), fixed holidays (every contact of the shop), or the first completed order exactly `days` ago. **Výstupy:** `next` · **Povinné na zapnutie:** `kind`, `at` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `kind` | one of: `name_day`, `birthday`, `first_order`, `custom_date`, `holiday` | áno | Kind of date. | | `days` | integer | nie | first_order: days after the first order, 1 to 3 650. min 1, max 3650 | | `field` | string | nie | custom_date: cf: of a date custom field. | | `dates` | array of string | nie | holiday: days of the year MM-DD (at most 366, unique). min 1 items, max 366 items | | `offsetDays` | integer | nie | name_day, birthday, custom_date: shift -365 to 365 (e.g. -3 = three days before). min -365, max 365 | | `at` | string | áno | HH:MM local time of the daily pass. pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-date-1", "type": "trigger_date", "config": { "kind": "name_day", "at": "08:00", "reentry": "parallel" } } ``` #### `trigger_reorder` {#node-trigger-reorder} Starts once a day at `at` for customers whose last completed order is older than their usual interval between orders ("buy again"): the average gap of their order days, defaultDays with one order day, clamped to minDays..maxDays, plus graceDays. **Výstupy:** `next` · **Povinné na zapnutie:** `at` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `at` | string | áno | HH:MM. pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `defaultDays` | integer | nie | 1 to 365, default 30. default `30`, min 1, max 365 | | `minDays` | integer | nie | 1 to 365, default 14. default `14`, min 1, max 365 | | `maxDays` | integer | nie | 1 to 365 and >= minDays, default 120. default `120`, min 1, max 365 | | `graceDays` | integer | nie | 0 to 365, default 0. default `0`, min 0, max 365 | | `reentry` | one of: `parallel`, `restart`, `skip`, `once` | nie | What happens when a contact meets the trigger again: parallel (one more run, at most the company's limit of parallel runs; default for new triggers), restart (the new entry ends the running one), skip (nobody enters while their run is active; default of triggers saved without the setting), once (one run per contact for ever). | ```json { "id": "trigger-reorder-1", "type": "trigger_reorder", "config": { "at": "10:00", "defaultDays": 30, "minDays": 14, "maxDays": 120, "graceDays": 3, "reentry": "parallel" } } ``` ### Operátory #### `condition` {#node-condition} Splits the run: output yes when the definition holds, else no. With waitUntilMet the contact waits until it holds (then yes) or the time runs out (then no); checked every 20 minutes to once a day. **Výstupy:** `yes`, `no` · **Povinné na zapnutie:** `definition` · SmartEmailing: `condition` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `definition` | `ConditionGroup` | áno | | | `waitUntilMet` | object | nie | Wait for the definition up to this long (15 minutes to 10 years). | | `waitUpTo` | object | nie | Older form of waitUntilMet (hours or days, at most 30 days). | ```json { "id": "condition-1", "type": "condition", "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "email_activity", "operator": "opened", "nodeId": null } ] } } } ``` #### `wait` {#node-wait} Waits. mode time: until the time spec (relative to the arrival at the node, or to the entry with countFrom scenario); preferred: until the contact's usual reading time (most frequent quarter hour of opens, else no wait); spread: releases the contacts evenly over the period; duration: value units; time_of_day: the next HH:MM; weekday: the next listed weekday at time; date: a local date and time. At most 10 years. **Výstupy:** `next` · **Povinné na zapnutie:** `mode` · SmartEmailing: `wait` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `mode` | one of: `time`, `preferred`, `spread`, `duration`, `time_of_day`, `weekday`, `date` | áno | Mode. | | `spec` | `TimeSpec` | nie | | | `countFrom` | one of: `node`, `scenario` | nie | time: node (default) or scenario. | | `spread` | object | nie | spread: period over which contacts are released. | | `value` | integer | nie | duration: 1 to 100 000. min 1, max 100000 | | `unit` | one of: `minutes`, `hours`, `days`, `weeks`, `months`, `years` | nie | duration: unit. | | `time` | string | nie | time_of_day, weekday: HH:MM. pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | | `weekdays` | array of integer | nie | weekday: 1 (Monday) to 7, unique. min 1 items | | `date` | string | nie | date: YYYY-MM-DDTHH:MM local. pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$` | ```json { "id": "wait-1", "type": "wait", "config": { "mode": "duration", "value": 2, "unit": "days" } } ``` #### `ab_test` {#node-ab-test} Splits contacts randomly (stable per run) into 2 to 10 variants; outputs v1..vN. **Výstupy:** `v1`, `...`, `v10` · **Povinné na zapnutie:** `variants` · SmartEmailing: `ab` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `variants` | array of object | áno | 2 to 10 variants {key: "v1".."vN" in order, share 1..99}, shares sum to 100. min 2 items, max 10 items | ```json { "id": "ab-test-1", "type": "ab_test", "config": { "variants": [ { "key": "v1", "share": 50 }, { "key": "v2", "share": 50 } ] } } ``` #### `holding` {#node-holding} Storage (Odkladiště): contacts wait here until an edge out of the node is added (then they continue) or 90 days pass. **Výstupy:** `next` · SmartEmailing: `storage` Bez nastavení. ```json { "id": "holding-1", "type": "holding", "config": {} } ``` #### `goal` {#node-goal} Goal of the scenario: before every step the goals are checked; a contact who meets one leaves the scenario wherever it is. No edges in or out. **Výstupy:** - · **Povinné na zapnutie:** `definition` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `definition` | `ConditionGroup` | áno | | ```json { "id": "goal-1", "type": "goal", "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "operator": "yes", "shopId": null } ] } } } ``` ### Akcie #### `send_email` {#node-send-email} Sends an e-mail from a template (once per node and contact within the company's window). Only to mailable contacts, rechecked right before sending. **Výstupy:** `next` · **Povinné na zapnutie:** `templateId` · SmartEmailing: `send-email` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `templateId` | string | áno | Template with content (GET /templates). Required. | | `templateRef` | string | nie | Information only (definition files). | | `subject` | string | nie | Subject, at most 200 characters; default the template's. | | `preheader` | string | nie | Preheader, at most 300; default the template's. | | `senderId` | string | nie | Sender of the automation's shop (GET /senders); default the shop's default sender. Must be verified to activate. | | `senderName` | string | nie | Sender name, at most 100. | | `replyTo` | string | nie | Reply-To e-mail address. | | `trackOpens` | boolean | nie | Default true. | | `trackClicks` | boolean | nie | Default true. | | `trackingParams` | object | nie | UTM parameters added to links. | | `headers` | object | nie | Own e-mail headers. | | `unsubscribePageId` | string | nie | Own unsubscribe page of this node (GET /unsubscribe-pages). | | `controlAddress` | string | nie | Send every e-mail of this node only to this test address of the company (GET /test-recipients) instead of the contact; for checking a live scenario. | ```json { "id": "send-email-1", "type": "send_email", "config": { "templateId": "301", "subject": "Zapomněli jste něco v košíku", "trackOpens": true, "trackClicks": true } } ``` #### `list_change` {#node-list-change} Sets the contact's state in manual lists (confirmed adds, unsubscribed and removed take out). Lists bound to an e-shop cannot be changed. **Výstupy:** `next` · **Povinné na zapnutie:** `status`, `listIds` · SmartEmailing: `add-to-list` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `status` | one of: `confirmed`, `unsubscribed`, `removed` | áno | New state. | | `action` | one of: `add`, `remove` | nie | Older form: add = confirmed, remove = removed. | | `listIds` | array of string | áno | 1 to 20 manual or form list ids, unique. min 1 items, max 20 items | | `listRefs` | array of string | nie | Information only. | ```json { "id": "list-change-1", "type": "list_change", "config": { "status": "confirmed", "listIds": [ "101" ] } } ``` #### `webhook` {#node-webhook} Calls a URL (queued, retried 5 times 5 minutes apart on a non-2xx answer, then an action failure "other"). Merge tags work in url (percent-encoded), body (JSON-escaped when the Content-Type is JSON; POST defaults to application/json) and header values. Only public addresses, no redirects. **Výstupy:** `next` · **Povinné na zapnutie:** `url` · SmartEmailing: `send-webhook` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `url` | string | áno | http(s) URL or one starting with a merge tag, at most 2 000. | | `method` | one of: `GET`, `POST` | nie | Default POST. default `POST` | | `body` | string | nie | POST body, at most 10 000 characters (merge tags allowed). | | `headers` | array of object | nie | At most 20 {name, value}. max 20 items | | `basicAuth` | object | nie | HTTP Basic of the call. password is write only: answers show passwordSet. | ```json { "id": "webhook-1", "type": "webhook", "config": { "url": "https://crm.example.cz/hooks/postarna", "method": "POST", "body": "{\"email\": \"{{df_emailaddress}}\", \"event\": \"cart\"}", "headers": [ { "name": "X-Source", "value": "postarna" } ] } } ``` #### `set_field` {#node-set-field} Sets or clears a contact field. valueKind fixed (a value of the field's type), relative (dates: a time spec from now) or template (text fields: merge tags). **Výstupy:** `next` · **Povinné na zapnutie:** `field`, `action` · SmartEmailing: `set-field` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `field` | string | áno | System field (firstName, lastName, titleBefore, titleAfter, company, companyId, phone, mobile, street, city, postalCode, note, affiliateId, salutation, salutationFormal, vocativeFirstName, vocativeLastName, gender, language, country, birthday, nameDay) or cf:. | | `action` | one of: `set`, `clear` | áno | Action. | | `valueKind` | one of: `fixed`, `relative`, `template` | nie | Default fixed. default `fixed` | | `value` | any | nie | set only: by field kind: text (at most 200), textarea (1 000), gender f / m, language xx, country XX, date YYYY-MM-DD, name day MM-DD, number as string, checkbox true / false, select / radio an option, multi_checkbox a list of options. | ```json { "id": "set-field-1", "type": "set_field", "config": { "field": "cf:62", "action": "set", "valueKind": "fixed", "value": "VIP" } } ``` #### `reset` {#node-reset} Ends the contact's other active runs of this scenario that wait in nodes after this one (SmartEmailing Reset). **Výstupy:** `next` · SmartEmailing: `reset` Bez nastavení. ```json { "id": "reset-1", "type": "reset", "config": {} } ``` #### `fire_event` {#node-fire-event} Fires a custom event of the contact that event triggers (custom) of OTHER automations listen to. **Výstupy:** `next` · **Povinné na zapnutie:** `name` · SmartEmailing: `fire-event` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `name` | string | áno | a-z, 0-9 and - (1 to 50), not starting with se-. pattern `^[a-z0-9-]{1,50}$` | | `data` | object | nie | Event data, at most 2 000 characters as JSON. | ```json { "id": "fire-event-1", "type": "fire_event", "config": { "name": "vip-reached", "data": { "level": "gold" } } } ``` #### `notify` {#node-notify} Notifies the team in the app (notification centre). **Výstupy:** `next` · **Povinné na zapnutie:** `message` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `message` | string | áno | 1 to 500 characters. | | `important` | boolean | nie | Mark as important, default false. | ```json { "id": "notify-1", "type": "notify", "config": { "message": "Zákazník dosáhl VIP úrovně", "important": false } } ``` #### `goto` {#node-goto} Jumps to another node of this graph (not a trigger or goal; the jump counts as an edge for cycles, so only forward). **Výstupy:** - · **Povinné na zapnutie:** `target` | Pole | Typ | Povinné | Popis | |---|---|---|---| | `target` | string | áno | Key of the target node. | #### `end` {#node-end} Ends the run (the contact leaves). **Výstupy:** - Bez nastavení. ```json { "id": "end-1", "type": "end", "config": {} } ``` ### Zatiaľ nedostupné | Typ | Chýba | |---|---| | `send_sms` | sms | | `send_viber` | viber | | `fb_audience` | meta | | `sklik_retargeting` | sklik | | `motionlab_adina` | motionlab | | `whatsapp` | whatsapp | ## Podmienky automatizácií {#podminky-automatizaci} Pravidlá uzla `condition`, cieľa a filtru spúšťačov (spolu s pravidlami segmentov nižšie). Každé smie mať `negate`. #### `ab_test_significant` {#cond-ab-test-significant} The difference between nodes A and B is significant (95 %, two-proportion z-test). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ab_test_significant` | áno | | | `metric` | one of: `open_rate`, `click_rate` | áno | Metric. | | `nodeA` | string | áno | send_email node key. | | `nodeB` | string | áno | Another send_email node key. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | #### `ab_test_winner` {#cond-ab-test-winner} Node A beats node B (two send_email nodes of this graph) in open or click rate. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ab_test_winner` | áno | | | `metric` | one of: `open_rate`, `click_rate` | áno | Metric. | | `nodeA` | string | áno | send_email node key. | | `nodeB` | string | áno | Another send_email node key. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | #### `cart_items` {#cond-cart-items} Old name of cart_items_count (still accepted). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `cart_items` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number. | | `shopId` | string or null | nie | | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "cart_items", "operator": "gt", "value": 0 } ``` #### `cart_items_count` {#cond-cart-items-count} Items in the contact's cart (a cart not changed since an order counts as empty). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `cart_items_count` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number. | | `shopId` | string or null | nie | Shop, null = any cart. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "cart_items_count", "operator": "gt", "value": 0, "shopId": "1" } ``` #### `contact_anniversary` {#cond-contact-anniversary} Today is (or is offset from) the contact's birthday, name day or a date custom field. nameDay: the contact's own name day, else the calendar of the first name (calendar auto = Slovak for language sk, else by the shop's language). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_anniversary` | áno | | | `field` | string | áno | birthday, nameDay or cf: of a date field. | | `calendar` | one of: `auto`, `cz`, `sk` | nie | nameDay only. | | `relation` | one of: `now`, `offset` | nie | now = today; offset = shifted. default `now` | | `offset` | object | nie | With relation offset, at least 15 minutes. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "contact_anniversary", "field": "nameDay", "calendar": "auto", "relation": "now" } ``` #### `contact_field` {#cond-contact-field} A contact field (system field or cf:) compared with a value. Text: eq, filled, empty, gt, gte, lt, lte, starts, contains; dates: date_eq, date_filled, date_empty, date_after, date_from, date_before, date_until with a time spec value; numbers: eq, gt, gte, lt, lte, filled, empty; gender: eq (f / m); checkbox: checked, unchecked; choice: eq_option; multi: has_option. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_field` | áno | | | `field` | string | áno | System field (affiliateId, domain, email, language, firstName, mobile, city, birthday, vocativeFirstName, salutation, salutationFormal, vocativeLastName, gender, note, lastName, postalCode, company, nameDay, phone, titleBefore, titleAfter, street, createdAt, country, companyId) or cf:. | | `operator` | string | áno | Operator for the field kind. | | `value` | any | nie | Text, number, f / m, an option, or a time spec for dates. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "contact_field", "field": "city", "operator": "eq", "value": "Brno" } ``` #### `contact_in_any_list` {#cond-contact-in-any-list} Contact is in any list in a state. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_in_any_list` | áno | | | `state` | one of: `confirmed`, `unsubscribed` | nie | State, default confirmed. default `confirmed` | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | ```json { "type": "contact_in_any_list" } ``` #### `contact_in_automation` {#cond-contact-in-automation} Contact is in an automation (another active run of it). automationId null = this automation (not allowed in a trigger filter). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_in_automation` | áno | | | `automationId` | string or null | nie | | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "contact_in_automation", "automationId": "201" } ``` #### `contact_in_list` {#cond-contact-in-list} Contact is in a list in a state. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_in_list` | áno | | | `listId` | string | áno | List id. | | `state` | one of: `confirmed`, `unsubscribed` | nie | State, default confirmed. default `confirmed` | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | ```json { "type": "contact_in_list", "listId": "101", "state": "confirmed" } ``` #### `contact_in_list_label` {#cond-contact-in-list-label} Contact is in a list with this label. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_in_list_label` | áno | | | `label` | string | áno | Label, at most 40. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | ```json { "type": "contact_in_list_label", "label": "newsletter" } ``` #### `contact_origin` {#cond-contact-origin} Contact came from a source. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_origin` | áno | | | `origin` | one of: `erp_order`, `signup_form`, `import`, `api`, `manual`, `shoptet`, `smartemailing` | áno | Source. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "contact_origin", "origin": "signup_form" } ``` #### `contact_purpose` {#cond-contact-purpose} Contact has a valid consent with a purpose. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `contact_purpose` | áno | | | `purposeId` | string | áno | Purpose id. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | ```json { "type": "contact_purpose", "purposeId": "51" } ``` #### `day_of_month` {#cond-day-of-month} Today is one of these days of the month. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `day_of_month` | áno | | | `days` | array of integer | áno | Days 1 to 31. min 1 items | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "day_of_month", "days": [ 1, 15 ] } ``` #### `day_of_week` {#cond-day-of-week} Today is one of these weekdays (1 = Monday). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `day_of_week` | áno | | | `weekdays` | array of integer | áno | 1 to 7. min 1 items | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "day_of_week", "weekdays": [ 6, 7 ] } ``` #### `email_activity` {#cond-email-activity} The contact opened / clicked an e-mail of this run (nodeId null = any). Run only. (not allowed in trigger filters (needs a run)) | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `email_activity` | áno | | | `operator` | one of: `opened`, `not_opened`, `clicked`, `not_clicked` | áno | Operator. | | `nodeId` | string or null | nie | send_email node key. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "email_activity", "operator": "opened", "nodeId": null } ``` #### `engagement_score` {#cond-engagement-score} Engagement level of the contact. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `engagement_score` | áno | | | `levels` | array of one of: `N`, `A`, `B`, `C`, `D`, `E` | áno | Levels. min 1 items | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "engagement_score", "levels": [ "A", "B" ] } ``` #### `event_attribute` {#cond-event-attribute} A value of the data of the custom event that started the run (data of POST /contact-events type custom, or of a fire_event node of another automation). Other triggers have no such data. Run only. (not allowed in trigger filters (needs a run)) | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `event_attribute` | áno | | | `attribute` | string | áno | Name. | | `operator` | one of: `eq`, `contains`, `starts`, `gt`, `gte`, `lt`, `lte`, `filled`, `empty` | áno | Operator. | | `value` | string | nie | Text. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "event_attribute", "attribute": "plan", "operator": "eq", "value": "gold" } ``` #### `feed_item_count` {#cond-feed-item-count} Number of items of a feed. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `feed_item_count` | áno | | | `feedId` | string | áno | Feed id. | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "feed_item_count", "feedId": "71", "operator": "gt", "value": 0 } ``` #### `hour_of_day` {#cond-hour-of-day} The current hour (local) is one of these. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `hour_of_day` | áno | | | `hours` | array of integer | áno | 0 to 23. min 1 items | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "hour_of_day", "hours": [ 8, 9, 10 ] } ``` #### `opened_email` {#cond-opened-email} The contact opened an e-mail of a node. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `opened_email` | áno | | | `emailNode` | object | áno | An e-mail node: automationId null (or left out) = a send_email node of this graph, else the id of another automation of the company and its node key. | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "opened_email", "emailNode": { "automationId": "201", "nodeKey": "email-1" } } ``` #### `opened_emails_count` {#cond-opened-emails-count} Number of e-mails the contact opened. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `opened_emails_count` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number. | | `kinds` | array of one of: `automation`, `campaign`, `transactional` | nie | Kinds. | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "opened_emails_count", "operator": "eq", "value": 0 } ``` #### `ordered_attribute` {#cond-ordered-attribute} A value of an order: code, state, status, sourceStatus, currency, companyId, totalWithVat, totalWithoutVat, or any delivery data field. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ordered_attribute` | áno | | | `attribute` | string | áno | Attribute name: letters, digits and _ . : - (at most 60). | | `attributeType` | one of: `text`, `date`, `number` | nie | How to compare. default `text` | | `operator` | one of: `eq`, `filled`, `gt`, `gte`, `lt`, `lte`, `starts` | áno | Operator. | | `value` | any | nie | Text, a number, or a time spec for attributeType date. | | `limitToTriggerEvent` | boolean | nie | Only the order of the run's own trigger event (order triggers). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "ordered_attribute", "attribute": "currency", "operator": "eq", "value": "CZK" } ``` #### `ordered_product` {#cond-ordered-product} The contact ordered a product by id (product code) or name. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ordered_product` | áno | | | `productField` | one of: `id`, `name` | nie | Field, default id. default `id` | | `operator` | one of: `eq`, `starts`, `contains` | áno | Operator. | | `value` | string | áno | Text. | | `limitToTriggerEvent` | boolean | nie | Only the order of the run's own trigger event (order triggers). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "ordered_product", "productField": "id", "operator": "eq", "value": "SKU-001" } ``` #### `ordered_product_by_attribute` {#cond-ordered-product-by-attribute} The contact ordered a product with a feed attribute. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ordered_product_by_attribute` | áno | | | `attribute` | string | áno | Attribute name: letters, digits and _ . : - (at most 60). | | `attributeType` | one of: `text`, `date`, `number` | nie | How to compare. default `text` | | `operator` | one of: `eq`, `filled`, `gt`, `gte`, `lt`, `lte`, `starts` | áno | Operator. | | `value` | any | nie | Text, a number, or a time spec for attributeType date. | | `limitToTriggerEvent` | boolean | nie | Only the order of the run's own trigger event (order triggers). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "ordered_product_by_attribute", "attribute": "brand", "operator": "eq", "value": "Example" } ``` #### `ordered_since_entry` {#cond-ordered-since-entry} The contact ordered since the run entered. Run only. (not allowed in trigger filters (needs a run)) | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `ordered_since_entry` | áno | | | `operator` | one of: `yes`, `no` | áno | Operator. | | `shopId` | string or null | nie | | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "ordered_since_entry", "operator": "yes", "shopId": null } ``` #### `orders_count` {#cond-orders-count} Number of orders. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `orders_count` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number. | | `paid` | one of: `any`, `yes`, `no` | nie | Paid filter, default any. default `any` | | `states` | array of one of: `received`, `processing`, `shipped`, `cancelled`, `unknown` | nie | Order states (SmartEmailing names). | | `shopId` | string or null | nie | | | `limitToTriggerEvent` | boolean | nie | Only the order of the run's own trigger event (order triggers). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "orders_count", "operator": "eq", "value": 1, "paid": "any" } ``` #### `orders_total_value` {#cond-orders-total-value} Sum (or avg, min, max) of the contact's orders with VAT in one currency. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `orders_total_value` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Number. | | `aggregate` | one of: `sum`, `avg`, `min`, `max` | nie | Aggregate, default sum. default `sum` | | `currency` | string | áno | Currency of a shop of the company (CZK, EUR). | | `shopId` | string or null | nie | | | `limitToTriggerEvent` | boolean | nie | Only the order of the run's own trigger event (order triggers). | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "orders_total_value", "operator": "gte", "value": "3000", "currency": "CZK" } ``` #### `passed_node` {#cond-passed-node} This run went (or did not go) through a node. Run only. (not allowed in trigger filters (needs a run)) | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `passed_node` | áno | | | `operator` | one of: `passed`, `not_passed` | áno | Operator. | | `nodeId` | string | áno | Node key. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | #### `promo_code` {#cond-promo-code} The contact got (assigned) or used a coupon of a stack. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `promo_code` | áno | | | `state` | one of: `assigned`, `used` | áno | State. | | `stackId` | string | áno | Coupon stack id. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "promo_code", "state": "used", "stackId": "81" } ``` #### `script` {#cond-script} A Twig script; true when it prints {{ result.returnTrue() }}. Not allowed in trigger filters. (not allowed in trigger filters (needs a run)) | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `script` | áno | | | `script` | string | áno | Twig source, at most 20 000 characters. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "script", "script": "{% if contact.city == 'Brno' %}{{ result.returnTrue() }}{% endif %}" } ``` #### `sent_email` {#cond-sent-email} An e-mail was sent to the contact: of one node (mode node) or of an automation (mode automation, automationId null = any). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `sent_email` | áno | | | `mode` | one of: `node`, `automation` | áno | Mode. | | `emailNode` | object | nie | An e-mail node: automationId null (or left out) = a send_email node of this graph, else the id of another automation of the company and its node key. | | `automationId` | string or null | nie | | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "sent_email", "mode": "node", "emailNode": { "automationId": "201", "nodeKey": "email-1" } } ``` #### `sent_emails_count` {#cond-sent-emails-count} Number of e-mails sent to the contact. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `sent_emails_count` | áno | | | `operator` | one of: `eq`, `lt`, `lte`, `gt`, `gte` | áno | Operator. | | `value` | any | áno | Whole number 0 to 10 000 000. | | `kinds` | array of one of: `automation`, `campaign`, `transactional` | nie | Kinds, default automation and campaign. | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "sent_emails_count", "operator": "gte", "value": 3 } ``` #### `tracking_url_clicked` {#cond-tracking-url-clicked} The contact clicked a link in an e-mail of a node. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `tracking_url_clicked` | áno | | | `emailNode` | object | áno | An e-mail node: automationId null (or left out) = a send_email node of this graph, else the id of another automation of the company and its node key. | | `link` | string | áno | URL (at most 2 000). | | `compareParams` | boolean | nie | Compare query parameters too, default true. default `true` | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "tracking_url_clicked", "emailNode": { "automationId": "201", "nodeKey": "email-1" }, "link": "https://www.example.cz/akce" } ``` #### `tracking_url_clicked_any` {#cond-tracking-url-clicked-any} The contact clicked any link of a node (emailNode null = any e-mail node of this automation). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `tracking_url_clicked_any` | áno | | | `emailNode` | object or null | nie | | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "tracking_url_clicked_any", "emailNode": null } ``` #### `visited_attribute` {#cond-visited-attribute} A web tracking visit with an attribute. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `visited_attribute` | áno | | | `url` | string | nie | URL. | | `urlOperator` | one of: `eq`, `starts` | nie | Default eq. default `eq` | | `visitType` | one of: `home`, `article`, `cart`, `product`, `category`, `search`, `order_done`, `other` | nie | Visit type. | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `attribute` | string | áno | Attribute name: letters, digits and _ . : - (at most 60). | | `attributeType` | one of: `text`, `date`, `number` | nie | How to compare. default `text` | | `value` | any | nie | Text, a number, or a time spec for attributeType date. | | `operator` | one of: `starts`, `gt`, `gte`, `lt`, `lte`, `eq` | áno | Operator. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "visited_attribute", "attribute": "category", "operator": "eq", "value": "Káva" } ``` #### `visited_url` {#cond-visited-url} A web tracking visit of a URL. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `visited_url` | áno | | | `url` | string | nie | URL. | | `urlOperator` | one of: `eq`, `starts`, `contains` | nie | Default eq. default `eq` | | `visitType` | one of: `home`, `article`, `cart`, `product`, `category`, `search`, `order_done`, `other` | nie | Visit type. | | `period` | object | nie | Time window of the rule: from and to are time specs relative to now (null = unbounded). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "visited_url", "url": "https://www.example.cz/kosik", "urlOperator": "starts" } ``` #### Zatiaľ nedostupné podmienky | Typ | Chýba | |---|---| | `contact_preference` | preferences | | `contact_viber_state` | viber | | `delivered_viber` | viber | | `score` | scoring | | `seen_viber` | viber | | `sent_sms` | sms | ## Pravidlá segmentov {#pravidla-segmentu} Pravidlá segmentov (a podmienok automatizácií). Hodnoty sú reťazce. #### `campaign` {#rule-campaign} Delivered / opened / clicked a campaign (not_* also matches contacts that never got it); linkUrl narrows clicks to one link. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `campaign` | áno | | | `operator` | one of: `received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked` | áno | Operator. | | `campaignId` | string or null | áno | Campaign id; null only with received = an e-mail of any campaign. | | `linkUrl` | string | nie | clicked / not_clicked only. | | `days` | string or null | nie | Last N days or null. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "campaign", "operator": "opened", "campaignId": "121", "days": null } ``` #### `custom_field` {#rule-custom-field} 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..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. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `custom_field` | áno | | | `fieldId` | string | áno | Custom field id (without cf:). | | `kind` | one of: `bool`, `choice`, `date`, `multi_choice`, `number`, `text` | áno | Kind of the field type (see above). | | `operator` | string | áno | Operator for the kind. | | `value` | string | nie | Value (string). | | `values` | array of string | nie | Options (multi_choice). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "custom_field", "fieldId": "62", "kind": "text", "operator": "equals", "value": "VIP" } ``` #### `engagement` {#rule-engagement} Engagement level A (best) to E, N = new. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `engagement` | áno | | | `operator` | one of: `in`, `not_in` | áno | Operator. | | `values` | array of one of: `A`, `B`, `C`, `D`, `E`, `N` | áno | Levels. min 1 items | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "engagement", "operator": "in", "values": [ "A", "B" ] } ``` #### `field` {#rule-field} 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. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `field` | áno | | | `field` | one of: `email`, `firstName`, `lastName`, `city`, `company`, `companyId`, `phone`, `mobile`, `street`, `postalCode`, `note`, `country`, `status`, `gender`, `language`, `source`, `consentBasis`, `createdAt`, `lastOpenAt`, `lastClickAt`, `lastSentAt`, `statusAt`, `consentAt` | áno | Contact field. | | `operator` | one of: `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` | áno | 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` | string | áno | 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` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "field", "field": "lastOpenAt", "operator": "in_last_days", "value": "60" } ``` #### `last_order` {#rule-last-order} The last completed order: within / older than N days, or before / after a date. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `last_order` | áno | | | `operator` | one of: `in_last_days`, `older_than_days`, `before`, `after` | áno | Operator. | | `value` | string | áno | Days "1" to "3650" or a date YYYY-MM-DD. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `shopId` | string or null | nie | Only orders of this shop (null = any). | | `currency` | string or null | nie | Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set). | ```json { "type": "last_order", "operator": "older_than_days", "value": "180" } ``` #### `list` {#rule-list} 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. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `list` | áno | | | `operator` | one of: `in`, `not_in`, `added_before`, `added_after`, `status_is`, `longer_than_days`, `shorter_than_days` | áno | Operator. | | `listId` | string | áno | List id. | | `value` | string | nie | status_is: confirmed, unconfirmed, unsubscribed, removed; added_*: YYYY-MM-DD; *_than_days: days "1" to "3650". | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "list", "operator": "in", "listId": "101" } ``` #### `list_label` {#rule-list-label} Confirmed or unconfirmed member of any list with this label. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `list_label` | áno | | | `operator` | one of: `in` | áno | Operator. | | `label` | string | áno | Label, 1 to 40. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "list_label", "operator": "in", "label": "vip" } ``` #### `opens` {#rule-opens} Number of the contact's e-mails (campaigns and automations) with an open. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `opens` | áno | | | `operator` | one of: `eq`, `gt`, `lt`, `gte`, `lte` | áno | Operator. | | `value` | string | áno | Count "0" to "100000". | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "opens", "operator": "gte", "value": "3", "days": "90" } ``` #### `order_attribute` {#rule-order-attribute} 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. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `order_attribute` | áno | | | `operator` | one of: `is` | áno | Operator. | | `scope` | one of: `item`, `order` | nie | item (default) or order. default `item` | | `attribute` | string | áno | item: productCode, category, brand or any attribute name; order: status, companyId, deliveryCity, deliveryCountry, deliveryZip, deliveryCompany. | | `value` | string | áno | Exact value, at most 200 characters. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `shopId` | string or null | nie | Only orders of this shop (null = any). | | `currency` | string or null | nie | Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set). | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | ```json { "type": "order_attribute", "operator": "is", "attribute": "brand", "value": "Example" } ``` #### `order_count` {#rule-order-count} Number of completed orders. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `order_count` | áno | | | `operator` | one of: `gte`, `lte`, `eq` | áno | Operator. | | `value` | string | áno | Count "0" to "100000". | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `shopId` | string or null | nie | Only orders of this shop (null = any). | | `currency` | string or null | nie | Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set). | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | ```json { "type": "order_count", "operator": "gte", "value": "2", "shopId": null, "currency": null, "days": "365" } ``` #### `order_value` {#rule-order-value} Sum of completed orders with VAT in one currency (CZK and EUR are never added up). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `order_value` | áno | | | `operator` | one of: `gte`, `lte` | áno | Operator. | | `amount` | string | áno | Amount, at most 2 decimals, e.g. "1500.50". | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `shopId` | string or null | nie | Only orders of this shop (null = any). | | `currency` | string or null | áno | Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set). | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | ```json { "type": "order_value", "operator": "gte", "amount": "2000", "currency": "CZK", "shopId": "1", "days": "365" } ``` #### `product_bought` {#rule-product-bought} A completed order has an item whose name contains the text or whose product code equals it (case and diacritics ignored). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `product_bought` | áno | | | `operator` | one of: `is` | áno | Operator. | | `value` | string | áno | Part of the name or the code, at most 200. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | | `shopId` | string or null | nie | Only orders of this shop (null = any). | | `currency` | string or null | nie | Only orders in this currency (CZK or EUR; it must be the currency of shopId when both are set). | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | ```json { "type": "product_bought", "operator": "is", "value": "Espresso", "days": "30" } ``` #### `purpose` {#rule-purpose} A valid (not withdrawn, within its validity) consent with a purpose of processing. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `purpose` | áno | | | `operator` | one of: `has`, `not_has` | áno | Operator. | | `purposeId` | string | áno | Purpose id. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "purpose", "operator": "has", "purposeId": "51" } ``` #### `segment` {#rule-segment} Member of another segment of the same shop (never itself; chains at most 5 deep, no cycles). | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `segment` | áno | | | `operator` | one of: `in`, `not_in`, `added_before`, `added_after` | áno | Operator. | | `segmentId` | string | áno | Segment id. | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "segment", "operator": "not_in", "segmentId": "91" } ``` #### `web_attribute` {#rule-web-attribute} A page visit whose attribute matches: visitType = the page type, other names = the visit's own attributes; gt to lte compare numbers. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `web_attribute` | áno | | | `attribute` | string | áno | Attribute name. | | `operator` | one of: `is`, `starts_with`, `gt`, `gte`, `lt`, `lte` | áno | Operator. | | `value` | string | áno | At most 200 (a number for gt to lte). | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "web_attribute", "attribute": "visitType", "operator": "is", "value": "product" } ``` #### `web_visit` {#rule-web-visit} A page visit recorded by the shop's script or the API; any = any page. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `type` | `web_visit` | áno | | | `operator` | one of: `any`, `is`, `starts_with`, `contains` | áno | Operator. | | `url` | string | nie | Not with any; at most 2 000. | | `days` | string or null | nie | Only the last N days, "1" to "3650" (null = any time). | | `negate` | boolean | nie | true = the rule must NOT hold (SmartEmailing "Neplatí, že"). | ```json { "type": "web_visit", "operator": "contains", "url": "/kava/", "days": "30" } ``` ## Časové údaje {#casove-udaje} A moment relative to a base moment (SmartEmailing's "Varianta výběru času"). The base is the moment the contact arrived at the node (or entered the scenario, countFrom scenario), or now in conditions. Days and longer keep the local wall time; months are calendar months. In waits only calendar, interval with sign "+" and event without the words yesterday and previous are allowed. Preview any spec with POST /automations/resolve-time. #### `calendar` A local calendar date and time. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `variant` | `calendar` | áno | | | `date` | string | áno | YYYY-MM-DD (local). pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$` | | `time` | string | nie | HH:MM (local), default 00:00. pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | #### `interval` Base plus or minus a number of units. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `variant` | `interval` | áno | | | `sign` | one of: `+`, `-` | áno | "+" later, "-" earlier (conditions only). | | `value` | integer | áno | 1 to 100 000. min 1, max 100000 | | `unit` | one of: `minutes`, `hours`, `days`, `weeks`, `months`, `years` | áno | Unit. | | `time` | string or null | nie | Optional HH:MM set after the shift (days and longer). pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | #### `event` A named day: today, tomorrow, this/next/previous weekday, working day, week, month or year, or the last day of this or next month. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `variant` | `event` | áno | | | `word` | one of: `yesterday`, `previous`, `today`, `this`, `tomorrow`, `next`, `last_day_of` | áno | Which day. | | `unit` | one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`, `workday`, `day`, `week`, `month`, `year` | nie | With previous, this and next: a weekday, workday, day, week, month or year; with last_day_of: month. | | `scope` | one of: `this`, `next` | nie | With last_day_of: this or next month. | | `time` | string | áno | HH:MM (local), required. pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$` | ```json [ { "variant": "interval", "sign": "+", "value": 2, "unit": "days", "time": "09:00" }, { "variant": "event", "word": "next", "unit": "monday", "time": "08:00" }, { "variant": "calendar", "date": "2026-12-24", "time": "09:00" } ] ``` --- # Objednávky, feedy a kupóny ## Objednávky {#objednavky} Objednávky poháňajú spúšťače (`order_created`, `order_completed`, `order_changed`), podmienky (počet a hodnota objednávok, objednaný produkt), segmenty a konverzie kampaní. Do Poštárne sa dostanú tromi cestami: konektorom e-shopu, feedom objednávok (`kind: shop_orders`) alebo API. ### `POST /orders`: založenie alebo úprava Objednávka sa ukladá podľa dvojice **(`shopId`, `id`)**, kde `id` je číslo objednávky vo vašom e-shope. Prvý zápis vráti 201 a `change: "created"`, ďalší 200 a `updated` alebo `unchanged`. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/orders" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "id": "2026001234", "shopId": "13", "createdAt": "2026-10-01T09:30:00+02:00", "paidAt": "2026-10-01T09:31:00+02:00", "email": "karel.vesely@example.cz", "status": "Zaplaceno", "eshopCode": "2026001234", "orderUrl": "https://www.example.cz/objednavka/2026001234", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": "1066.12", "items": [ { "id": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "quantity": 1, "unit": "ks", "price": { "withVat": "1290.00", "withoutVat": "1066.12", "currency": "CZK" }, "url": "https://www.example.cz/kava-kolumbie", "attributes": { "Category": "Káva", "Brand": "Example" } } ] } JSON ``` ```json title="Odpoveď: 201 Created" { "change": "created", "order": { "id": "5001", "externalId": "2026001234", "eshopCode": "2026001234", "eshopName": "Example.cz", "shopId": "13", "createdAt": "2026-10-01T07:30:00.000Z", "paidAt": "2026-10-01T07:31:00.000Z", "email": "karel.vesely@example.cz", "contactId": "1205", "state": "paid", "status": "completed", "sourceStatus": "Zaplaceno", "orderUrl": "https://www.example.cz/objednavka/2026001234", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": "1066.12", "itemCount": 1, "items": [ { "id": "1", "productCode": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "description": "", "price": { "withVat": "1290.00", "withoutVat": "1066.12", "currency": "CZK" }, "quantity": 1, "unit": "ks", "url": "https://www.example.cz/kava-kolumbie", "imageUrl": "", "attributes": { "Brand": "Example", "Category": "Káva" }, "paired": false } ], "conversion": null, "deleted": false, "receivedAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "seller": {}, "orderDelivery": {} } } ``` • `createdAt` (povinné) a `paidAt`: ISO 8601 s časovou zónou. • `email` alebo `contactId`: kupujúci. Kupujúci bez kontaktu dostane nový kontakt v stave `customer` (bez marketingového súhlasu, e-maily nedostáva). • `status`: **názov stavu vo vašom e-shope** (napríklad „Zaplatené“). Na kanonický stav ho prevedie mapa stavov (nižšie). • `currency`: smie byť len mena e-shopu; iná = 400. Sumy ako desatinné reťazce. • `items`: položky s `id` (kód produktu), `name` (povinné), `quantity`, `unit`, `price {withVat, withoutVat, currency}`, `url`, `imageUrl`, `attributes` (atribúty z feedu, napríklad `Category`, `Brand`; podľa nich pracuje pravidlo `order_attribute` a podmienky na produkty). • `deleted: true` = objednávka bola zmazaná (beh po nákupe sa ukončí). • Neznáme pole = 400 s jeho názvom. > **Pozor:** každý zápis **nahrádza celú objednávku**. Pole, ktoré pri úprave nepošlete, sa vyprázdni. Pri zmene stavu posielajte vždy celú objednávku. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/orders" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "id": "2026001234", "shopId": "13", "createdAt": "2026-10-01T09:30:00+02:00", "paidAt": "2026-10-01T09:31:00+02:00", "email": "karel.vesely@example.cz", "status": "Předáno zákazníkovi", "eshopCode": "2026001234", "currency": "CZK", "totalWithVat": "1290.00", "items": [ { "id": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "quantity": 1, "price": { "withVat": "1290.00", "currency": "CZK" } } ] } JSON ``` ```json title="Odpoveď: 200 OK" { "change": "updated", "order": { "id": "5001", "externalId": "2026001234", "eshopCode": "2026001234", "eshopName": "Example.cz", "shopId": "13", "createdAt": "2026-10-01T07:30:00.000Z", "paidAt": "2026-10-01T07:31:00.000Z", "email": "karel.vesely@example.cz", "contactId": "1205", "state": "paid", "status": "completed", "sourceStatus": "Předáno zákazníkovi", "orderUrl": "", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": null, "itemCount": 1, "items": [ { "id": "2", "productCode": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "description": "", "price": { "withVat": "1290.00", "withoutVat": null, "currency": "CZK" }, "quantity": 1, "unit": "", "url": "", "imageUrl": "", "attributes": {}, "paired": false } ], "conversion": null, "deleted": false, "receivedAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "seller": {}, "orderDelivery": {} } } ``` ### Mapa stavov {#mapa-stavu} | Kanonický stav (`state`) | Skupina (`status`) | |---|---| | `new`, `unpaid`, `processing` | `pending` | | `paid`, `shipped`, `delivered` | `completed` (nákup) | | `cancelled`, `returned` | `cancelled` | | `other` | `other` | `GET /order-states` ukáže pravidlá mapy a v `seen` názvy stavov, ktoré prišli v objednávkach, s ich výsledným stavom; `PUT /order-states` pravidlá nahradí: `{"items": [{"sourceStatus": "Zaplatené", "match": "exact", "state": "paid"}]}` (`match` `exact` alebo `prefix`, najviac 500 pravidiel). Prekrytie sa prejaví aj na uložených objednávkach. Názov bez mapovania je `other` a nikdy sa nepočíta ako nákup. ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/order-states" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/order-states" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "states": [ "new", "unpaid", "paid", "processing", "shipped", "delivered", "cancelled", "returned", "other" ], "items": [], "seen": [] } ``` ### Kedy objednávka spustí automatizáciu • `order_created`: nová objednávka; `order_completed`: objednávka sa prvý raz dostala do skupiny `completed`; `order_changed`: zmena stavu (voliteľne len do jedného stavu). • Objednávky z prvého importu feedu objednávok (história) a objednávky staršie než 2 dni vo feede automatizáciu nespúšťajú. Objednávka zapísaná cez `POST /orders` ju spúšťa. • Beh spustený objednávkou skončí, keď sa objednávka zruší, vráti alebo zmaže. • Každý e-shop by mal mať jediný zdroj objednávok (konektor, feed, alebo API); dva zdroje by uložili objednávky dvakrát. ## Feedy | `kind` | Čo je | Limit | |---|---|---| | `google_products` | produktový feed Google Merchant (XML): produkty pre šablóny (`data.products`), párovanie položiek objednávok, podmienky | 20 MB, 50 000 položiek | | `shop_customers` | export zákazníkov e-shopu (CSV alebo XML); zákazník nie je odberateľ, nevzniká kontakt ani súhlas | 100 MB, 500 000 záznamov | | `shop_orders` | export objednávok e-shopu (CSV), jeden na e-shop; sťahuje sa každú hodinu, posledné 3 dni každých 10 minút | 200 MB | | `articles` | článkový feed (RSS 2.0 alebo Atom), napríklad blog e-shopu, pre `data.articles` | | Produktový feed má `format` `google`, `heureka` alebo `zbozi` (zvolí sa pri založení). • `POST /feeds` s `{kind, name, shopId, url, autoRefresh}`, `POST /feeds/{id}/refresh` stiahne hneď, `GET /feeds/{id}/items` položky, `GET /feeds/{id}/preview` náhľad. • Tajná časť adresy (`hash`, `token`, `key`) sa v odpovediach maskuje. • Feedy patria do modulu `settings` (kľúč s rolou správcu účtu). ## Zľavové kupóny Zásobník (`coupon stack`) je sada jednorazových kódov jedného e-shopu: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "note": "Sleva 15 % k svátku" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "11", "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "tag": "{{coupon_svatek}}", "note": "Sleva 15 % k svátku", "counts": { "total": 0, "free": 0, "assigned": 0, "used": 0 }, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z" } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks/11/codes" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks/11/codes" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "text": "SVATEK-7Q2K\nSVATEK-9P4M\nSVATEK-3X8D\n" } JSON ``` ```json title="Odpoveď: 200 OK" { "counts": { "added": 3, "duplicate": 0, "invalid": 0, "total": 3 }, "stack": { "id": "11", "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "tag": "{{coupon_svatek}}", "note": "Sleva 15 % k svátku", "counts": { "total": 3, "free": 3, "assigned": 0, "used": 0 }, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z" } } ``` • V šablóne: `{{coupon_}}` alebo `{{ data.promoCode('') }}`. Každý e-mail dostane nový voľný kód a kód sa kontaktu priradí. • `POST /coupon-stacks/{id}/assign` priradí kód kontaktu ručne, `POST /coupon-stacks/{id}/used` označí kódy ako použité, `GET /contacts/{id}/coupons` kódy kontaktu. • Podmienka `promo_code` (dostal alebo použil kód zásobníka). • Dochádzajúce kódy zastavia e-mail (`customizationDataboxOutOfPromocodes`); sledujte `counts.free`. ## Konverzie Objednávka po prekliku z e-mailu sa pripočíta kampani alebo automatizácii ako konverzia: `GET /conversions` (súhrn po druhoch a menách), `GET /stats/campaigns/{id}/conversions`, `GET /stats/automations/{id}/conversions`. Tržby sú vždy po menách. --- # Recept: opustený košík **Cieľ:** zákazníkovi, ktorý si niečo vložil do košíka a do 2 hodín neobjednal, poslať pripomenutie. Keď košík medzitým vyprázdni alebo objedná, e-mail neodíde. **Potrebujete:** kľúč s rolou `marketing_manager` alebo `account_admin` (moduly `content` a `campaigns` plný prístup, `contacts` pre kontakty), overeného odosielateľa e-shopu, ID e-shopu (`GET /shops`). ## Ako to funguje ```text title="Graf" [kosik] trigger_event cart_updated (reentry restart) └─ next → [pockat] wait 2 hours └─ next → [stale-v-kosiku] condition: košík nie je prázdny A neobjednal od vstupu ├─ yes → [email] send_email (šablóna Opustený košík) └─ no → (koniec, kontakt scenár opustí) ``` • Každá zmena košíka (`POST /contact-events` typ `cart`) je udalosť `cart_updated`. Vďaka `reentry: "restart"` ďalšia zmena košíka ukončí rozbehnutý beh a čakanie začne znovu, takže zákazník dostane jedno pripomenutie až 2 hodiny po poslednej zmene. • Podmienka `cart_items_count` číta posledný stav košíka: prázdny košík (alebo košík, ktorý sa od objednávky nezmenil) má 0 položiek. • `ordered_since_entry: no` vylúči kontakty, ktoré od vstupu do scenára objednali. ## 1. Šablóna e-mailu V e-maile automatizácie sú dáta udalosti, ktorá beh spustila, v `metadata.event.attributes` (pri košíku `itemCount`, `total`, `currency`, `shopId`): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Opuštěný košík", "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku", "preheader": "Váš košík na vás počká ještě pár dní", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.

Dokončit objednávku

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "301", "name": "Opuštěný košík", "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku", "preheader": "Váš košík na vás počká ještě pár dní", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 465, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [ "subject_long" ], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.

Dokončit objednávku

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/1/72cf576a-85b2-474e-86e2-bfdbd1f4d38f" } ``` > **Nepodporované:** zoznam položiek košíka v e-maile. Dáta košíka nesú len počet kusov a súčet; odkaz vedie do košíka na e-shope. ## 2. Kontrola grafu bez uloženia `POST /automations/validate` ukáže chyby (`errors`, graf sa nedá uložiť) a neúplné nastavenia (`incomplete`, nejde zapnúť). Tu chýba šablóna e-mailu: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/validate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/validate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "shopId": "1", "graph": { "nodes": [ { "id": "kosik", "type": "trigger_event", "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } }, { "id": "pockat", "type": "wait", "config": { "mode": "duration", "value": 2, "unit": "hours" } }, { "id": "email", "type": "send_email", "config": {} } ], "edges": [ { "source": "kosik", "target": "pockat" }, { "source": "pockat", "target": "email" } ] } } JSON ``` ```json title="Odpoveď: 200 OK" { "errors": [], "incomplete": [ { "node": "email", "field": "templateId", "code": "required" } ] } ``` ## 3. Založenie automatizácie ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Opuštěný košík", "shopId": "1", "description": "Připomenutí košíku po 2 hodinách", "tags": [ "e-shop" ], "graph": { "nodes": [ { "id": "kosik", "type": "trigger_event", "name": "Změna košíku", "position": { "x": 0, "y": 0 }, "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } }, { "id": "pockat", "type": "wait", "name": "Počkat 2 hodiny", "position": { "x": 0, "y": 150 }, "config": { "mode": "duration", "value": 2, "unit": "hours" } }, { "id": "stale-v-kosiku", "type": "condition", "name": "Košík stále plný a bez objednávky", "position": { "x": 0, "y": 300 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "cart_items_count", "operator": "gt", "value": 0, "shopId": "1" }, { "type": "ordered_since_entry", "operator": "no", "shopId": "1" } ] } } }, { "id": "email", "type": "send_email", "name": "Připomenutí", "position": { "x": 0, "y": 450 }, "config": { "templateId": "301", "trackOpens": true, "trackClicks": true } } ], "edges": [ { "source": "kosik", "target": "pockat", "branch": "next" }, { "source": "pockat", "target": "stale-v-kosiku", "branch": "next" }, { "source": "stale-v-kosiku", "target": "email", "branch": "yes" } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "81", "name": "Opuštěný košík", "shopId": "1", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [ "e-shop" ], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "Připomenutí košíku po 2 hodinách", "graph": { "nodes": [ { "id": "kosik", "type": "trigger_event", "name": "Změna košíku", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } }, { "id": "pockat", "type": "wait", "name": "Počkat 2 hodiny", "note": "", "position": { "x": 0, "y": 150 }, "config": { "mode": "duration", "unit": "hours", "value": 2 } }, { "id": "stale-v-kosiku", "type": "condition", "name": "Košík stále plný a bez objednávky", "note": "", "position": { "x": 0, "y": 300 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "cart_items_count", "value": 0, "shopId": "1", "operator": "gt" }, { "type": "ordered_since_entry", "shopId": "1", "operator": "no" } ] } } }, { "id": "email", "type": "send_email", "name": "Připomenutí", "note": "", "position": { "x": 0, "y": 450 }, "config": { "templateId": "301", "trackOpens": true, "trackClicks": true } } ], "edges": [ { "source": "kosik", "target": "pockat", "branch": "next" }, { "source": "pockat", "target": "stale-v-kosiku", "branch": "next" }, { "source": "stale-v-kosiku", "target": "email", "branch": "yes" } ] }, "issues": [], "triggers": {} } ``` Automatizácia vznikne ako koncept (`status: "draft"`, verzia 1). Odpoveď má v `issues` všetko, čo bráni zapnutiu; tu je prázdne. ## 4. Zapnutie > **Pozor:** zapnutie posiela e-maily skutočným ľuďom. Skôr než automatizáciu zapnete, ukážte človeku spúšťač, e-maily a odosielateľa. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/81/activate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/activate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "81", "name": "Opuštěný košík", "shopId": "1", "status": "active", "version": 1, "activeSince": "2026-10-01T08:00:00.000Z", "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": null, "tags": [ "e-shop" ], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "Připomenutí košíku po 2 hodinách", "graph": { "nodes": [ { "id": "kosik", "type": "trigger_event", "name": "Změna košíku", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "cart_updated", "shopId": "1", "reentry": "restart" } }, { "id": "pockat", "type": "wait", "name": "Počkat 2 hodiny", "note": "", "position": { "x": 0, "y": 150 }, "config": { "mode": "duration", "unit": "hours", "value": 2 } }, { "id": "stale-v-kosiku", "type": "condition", "name": "Košík stále plný a bez objednávky", "note": "", "position": { "x": 0, "y": 300 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "cart_items_count", "value": 0, "shopId": "1", "operator": "gt" }, { "type": "ordered_since_entry", "shopId": "1", "operator": "no" } ] } } }, { "id": "email", "type": "send_email", "name": "Připomenutí", "note": "", "position": { "x": 0, "y": 450 }, "config": { "templateId": "301", "trackOpens": true, "trackClicks": true } } ], "edges": [ { "source": "kosik", "target": "pockat", "branch": "next" }, { "source": "pockat", "target": "stale-v-kosiku", "branch": "next" }, { "source": "stale-v-kosiku", "target": "email", "branch": "yes" } ] }, "issues": [], "triggers": {} } ``` Keď niečo chýba (neoverený odosielateľ, chyba v obsahu šablóny, neúplný uzol), server vráti 400 `validation` / `graph` s `params.issues`. ## 5. Udalosti košíka z e-shopu Pri každej zmene košíka prihláseného zákazníka pošlite aktuálny obsah. Kontakt nájde Poštárna podľa `email` alebo `contactId`; udalosť nikdy nezaloží nový kontakt (neznámy kontakt = 404). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "email": "lucie.mala@example.cz", "shopId": "1", "purposeId": "1", "consentConfirmed": true, "firstName": "Lucie", "vocativeFirstName": "Lucie" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "1201", "email": "lucie.mala@example.cz", "firstName": "Lucie", "lastName": "", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "1", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "Lucie", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": null, "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-1", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contact-events" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contact-events" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "type": "cart", "email": "lucie.mala@example.cz", "shopId": "1", "currency": "CZK", "total": "589.00", "items": [ { "code": "KAVA-250", "name": "Káva Brazílie 250 g", "quantity": 2, "price": "249.00", "url": "https://www.example.cz/kava-brazilie" }, { "code": "FILTR-02", "name": "Papírové filtry", "quantity": 1, "price": "91.00" } ] } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "9004" } ``` Vyprázdnený košík (alebo dokončenú objednávku) pošlite ako prázdne `items`: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contact-events" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contact-events" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "type": "cart", "contactId": "1201", "shopId": "1", "items": [] } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "9005" } ``` • Najviac 60 udalostí jedného kontaktu za 10 minút (429 `rate_limited`). Posielajte stav košíka po zmene, nie pri každom zobrazení stránky. • Objednávku zapíšte cez [`POST /orders`](https://www.postarna.sk/docs/api/orders-feeds-coupons#objednavky); podmienka `ordered_since_entry` ju uvidí. ## 6. Sledovanie Počty po uzloch (`waiting` = kontakty, ktoré práve čakajú): ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/automations/81/counts" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/counts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "nodes": {}, "runs": { "active": 0, "completed": 0, "exited": 0 } } ``` História jedného kontaktu: `GET /automations/{id}/runs?contactId=1201`. Priechod kontaktu bez odoslania: `POST /automations/{id}/trace` s `{"contactId": "1201"}`. ## 7. Úprava bežiacej automatizácie Bežiaci scenár sa dá uložiť len s `"confirmRunning": true`, inak 409 `confirm`: ```bash title="Požiadavka: PUT /api/v1/tenants/{tenant}/automations/81/graph" curl -sS -X PUT "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/graph" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "baseVersion": 1, "graph": { "nodes": [], "edges": [] } } JSON ``` ```json title="Odpoveď: 409 Conflict" { "error": { "code": "conflict", "message": "confirm" } } ``` ## Varianty • **Dve pripomenutia:** za e-mail pridajte `wait` (1 deň), znovu rovnakú podmienku a druhý `send_email`, napríklad so zľavou (`{{ data.promoCode('Košík') }}`). • **Len stáli zákazníci:** do podmienky pridajte pravidlo segmentu `order_count` (`"operator": "gte", "value": "1"`), alebo filter na vlastné pole kontaktu. • **Cieľ scenára:** uzol `goal` s pravidlom `ordered_since_entry: yes` ukončí beh, hneď ako zákazník objedná, kdekoľvek je. --- # Recept: séria po nákupe **Cieľ:** 3 dni po dokončení objednávky o 9:00 poslať poďakovanie s odkazom na hodnotenie; kto za 7 dní neklikne, dostane tip na použitie produktu. **Potrebujete:** kľúč s rolou `marketing_manager` (objednávky sú v module `contacts`, automatizácia v `campaigns`), mapu stavov objednávok (rola `account_admin` pre `PUT /order-states`). ## Graf ```text title="Graf" [objednavka] trigger_event order_completed (reentry parallel) → [3-dny] wait 3 days → [rano] wait time_of_day 09:00 → [jak-chutna] send_email → [7-dni] wait 7 days → [klikl] condition email_activity clicked (jak-chutna) ├─ yes → koniec └─ no → [tip] send_email ``` • `order_completed` nastane, keď sa objednávka prvý raz dostane do skupiny `completed` (zaplatená, odoslaná, doručená). • `reentry: "parallel"`: zákazník s druhou objednávkou dostane sériu znovu, aj keď tá prvá ešte beží. • Keď sa objednávka zruší, vráti alebo zmaže, beh skončí a ďalšie e-maily neodídu. ## 1. Mapa stavov objednávok Poštárna potrebuje vedieť, ktoré vaše stavy znamenajú nákup. Pozrite sa, čo už pozná: ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/order-states" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/order-states" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "states": [ "new", "unpaid", "paid", "processing", "shipped", "delivered", "cancelled", "returned", "other" ], "items": [], "seen": [] } ``` Chýbajúce stavy doplníte cez `PUT /order-states` (pozrite [mapa stavov](https://www.postarna.sk/docs/api/orders-feeds-coupons#mapa-stavu)). ## 2. Šablóny Dáta objednávky, ktorá beh spustila, sú v e-maile v `metadata.order` (položky v `metadata.order.items`): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Po nákupu: jak chutná", "subject": "Jak vám chutná?", "preheader": "Dejte nám vědět, jak jste spokojeni", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

{% set o = metadata.order %}{% if o %}

děkujeme za objednávku {{ o.eshop_code }}.

    {% for item in o.items %}
  • {{ item.name }}
    • {% endfor %}
{% endif %}

Napsat hodnocení

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "304", "name": "Po nákupu: jak chutná", "subject": "Jak vám chutná?", "preheader": "Dejte nám vědět, jak jste spokojeni", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 462, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

{% set o = metadata.order %}{% if o %}

děkujeme za objednávku {{ o.eshop_code }}.

    {% for item in o.items %}
  • {{ item.name }}
    • {% endfor %}
{% endif %}

Napsat hodnocení

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/7/558d86a4-2556-4849-b817-02b81558d85f" } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Po nákupu: tip na přípravu", "subject": "Tip, jak připravit kávu doma", "preheader": "Tři kroky k lepší kávě", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

tady jsou tři tipy, jak si doma připravit lepší kávu.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "305", "name": "Po nákupu: tip na přípravu", "subject": "Tip, jak připravit kávu doma", "preheader": "Tři kroky k lepší kávě", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 288, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

tady jsou tři tipy, jak si doma připravit lepší kávu.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/7/eafe9af1-437a-4904-be51-713bcd0113d9" } ``` ## 3. Automatizácia ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Po nákupu", "shopId": "13", "graph": { "nodes": [ { "id": "objednavka", "type": "trigger_event", "config": { "event": "order_completed", "reentry": "parallel" } }, { "id": "3-dny", "type": "wait", "config": { "mode": "duration", "value": 3, "unit": "days" } }, { "id": "rano", "type": "wait", "config": { "mode": "time_of_day", "time": "09:00" } }, { "id": "jak-chutna", "type": "send_email", "config": { "templateId": "304" } }, { "id": "7-dni", "type": "wait", "config": { "mode": "duration", "value": 7, "unit": "days" } }, { "id": "klikl", "type": "condition", "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "email_activity", "operator": "clicked", "nodeId": "jak-chutna" } ] } } }, { "id": "tip", "type": "send_email", "config": { "templateId": "305" } } ], "edges": [ { "source": "objednavka", "target": "3-dny" }, { "source": "3-dny", "target": "rano" }, { "source": "rano", "target": "jak-chutna" }, { "source": "jak-chutna", "target": "7-dni" }, { "source": "7-dni", "target": "klikl" }, { "source": "klikl", "target": "tip", "branch": "no" } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "84", "name": "Po nákupu", "shopId": "13", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "objednavka", "type": "trigger_event", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "order_completed", "reentry": "parallel" } }, { "id": "3-dny", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 3 } }, { "id": "rano", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "time_of_day", "time": "09:00" } }, { "id": "jak-chutna", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "304" } }, { "id": "7-dni", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "klikl", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "email_activity", "nodeId": "jak-chutna", "operator": "clicked" } ] } } }, { "id": "tip", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "305" } } ], "edges": [ { "source": "objednavka", "target": "3-dny", "branch": "next" }, { "source": "3-dny", "target": "rano", "branch": "next" }, { "source": "rano", "target": "jak-chutna", "branch": "next" }, { "source": "jak-chutna", "target": "7-dni", "branch": "next" }, { "source": "7-dni", "target": "klikl", "branch": "next" }, { "source": "klikl", "target": "tip", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/84/activate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/84/activate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "84", "name": "Po nákupu", "shopId": "13", "status": "active", "version": 1, "activeSince": "2026-10-01T08:00:00.000Z", "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "objednavka", "type": "trigger_event", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "order_completed", "reentry": "parallel" } }, { "id": "3-dny", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 3 } }, { "id": "rano", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "time_of_day", "time": "09:00" } }, { "id": "jak-chutna", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "304" } }, { "id": "7-dni", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "klikl", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "email_activity", "nodeId": "jak-chutna", "operator": "clicked" } ] } } }, { "id": "tip", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "305" } } ], "edges": [ { "source": "objednavka", "target": "3-dny", "branch": "next" }, { "source": "3-dny", "target": "rano", "branch": "next" }, { "source": "rano", "target": "jak-chutna", "branch": "next" }, { "source": "jak-chutna", "target": "7-dni", "branch": "next" }, { "source": "7-dni", "target": "klikl", "branch": "next" }, { "source": "klikl", "target": "tip", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` ## 4. Objednávky z e-shopu Pri vytvorení objednávky a pri každej zmene stavu pošlite celú objednávku. Kupujúci bez kontaktu dostane kontakt v stave `customer`, ktorý e-maily nedostáva; séria tak prijde len zákazníkom s marketingovým súhlasom. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/orders" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "id": "2026001234", "shopId": "13", "createdAt": "2026-10-01T09:30:00+02:00", "paidAt": "2026-10-01T09:31:00+02:00", "email": "karel.vesely@example.cz", "status": "Zaplaceno", "eshopCode": "2026001234", "orderUrl": "https://www.example.cz/objednavka/2026001234", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": "1066.12", "items": [ { "id": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "quantity": 1, "unit": "ks", "price": { "withVat": "1290.00", "withoutVat": "1066.12", "currency": "CZK" }, "url": "https://www.example.cz/kava-kolumbie", "attributes": { "Category": "Káva", "Brand": "Example" } } ] } JSON ``` ```json title="Odpoveď: 201 Created" { "change": "created", "order": { "id": "5001", "externalId": "2026001234", "eshopCode": "2026001234", "eshopName": "Example.cz", "shopId": "13", "createdAt": "2026-10-01T07:30:00.000Z", "paidAt": "2026-10-01T07:31:00.000Z", "email": "karel.vesely@example.cz", "contactId": "1205", "state": "paid", "status": "completed", "sourceStatus": "Zaplaceno", "orderUrl": "https://www.example.cz/objednavka/2026001234", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": "1066.12", "itemCount": 1, "items": [ { "id": "1", "productCode": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "description": "", "price": { "withVat": "1290.00", "withoutVat": "1066.12", "currency": "CZK" }, "quantity": 1, "unit": "ks", "url": "https://www.example.cz/kava-kolumbie", "imageUrl": "", "attributes": { "Brand": "Example", "Category": "Káva" }, "paired": false } ], "conversion": null, "deleted": false, "receivedAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "seller": {}, "orderDelivery": {} } } ``` Zmena stavu (pozor, zápis nahrádza celú objednávku, posielajte všetky polia): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/orders" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "id": "2026001234", "shopId": "13", "createdAt": "2026-10-01T09:30:00+02:00", "paidAt": "2026-10-01T09:31:00+02:00", "email": "karel.vesely@example.cz", "status": "Předáno zákazníkovi", "eshopCode": "2026001234", "currency": "CZK", "totalWithVat": "1290.00", "items": [ { "id": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "quantity": 1, "price": { "withVat": "1290.00", "currency": "CZK" } } ] } JSON ``` ```json title="Odpoveď: 200 OK" { "change": "updated", "order": { "id": "5001", "externalId": "2026001234", "eshopCode": "2026001234", "eshopName": "Example.cz", "shopId": "13", "createdAt": "2026-10-01T07:30:00.000Z", "paidAt": "2026-10-01T07:31:00.000Z", "email": "karel.vesely@example.cz", "contactId": "1205", "state": "paid", "status": "completed", "sourceStatus": "Předáno zákazníkovi", "orderUrl": "", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": null, "itemCount": 1, "items": [ { "id": "2", "productCode": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "description": "", "price": { "withVat": "1290.00", "withoutVat": null, "currency": "CZK" }, "quantity": 1, "unit": "", "url": "", "imageUrl": "", "attributes": {}, "paired": false } ], "conversion": null, "deleted": false, "receivedAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "seller": {}, "orderDelivery": {} } } ``` ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/orders/5001" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/orders/5001" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "5001", "externalId": "2026001234", "eshopCode": "2026001234", "eshopName": "Example.cz", "shopId": "13", "createdAt": "2026-10-01T07:30:00.000Z", "paidAt": "2026-10-01T07:31:00.000Z", "email": "karel.vesely@example.cz", "contactId": "1205", "state": "paid", "status": "completed", "sourceStatus": "Předáno zákazníkovi", "orderUrl": "", "currency": "CZK", "totalWithVat": "1290.00", "totalWithoutVat": null, "itemCount": 1, "items": [ { "id": "2", "productCode": "KAVA-1KG", "name": "Káva Kolumbie 1 kg", "description": "", "price": { "withVat": "1290.00", "withoutVat": null, "currency": "CZK" }, "quantity": 1, "unit": "", "url": "", "imageUrl": "", "attributes": {}, "paired": false } ], "conversion": null, "deleted": false, "receivedAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "seller": {}, "orderDelivery": {} } ``` ## Varianty • **Len prvý nákup:** do série pridajte za spúšťač podmienku `orders_count` (`"operator": "eq", "value": 1`). • **Podľa kategórie:** podmienka `ordered_product_by_attribute` s `"limitToTriggerEvent": true` a `"attribute": "Category"` vyberie len objednávky s produktom danej kategórie. • **Kúpte si znovu:** samostatná automatizácia so spúšťačom `trigger_reorder` pošle pripomenutie, keď zákazníkovi dochádza obvyklý interval medzi nákupmi. --- # Recept: meniny so zľavou **Cieľ:** každý deň o 8:00 poslať kontaktom, ktoré majú meniny, prianie s jednorazovým zľavovým kódom. **Potrebujete:** kľúč s rolou `account_admin` (zásobník kupónov je v module `settings`), zľavové kódy z e-shopu. ## Ako Poštárna pozná meniny • Kontakt s vyplneným poľom `nameDay` (`MM-DD`) oslavuje v ten deň. • Kontakt bez neho oslavuje podľa prvého slova krstného mena (bez ohľadu na veľké písmená a diakritiku) v kalendári svojho jazyka: slovenský pre jazyk `sk`, kontakt bez jazyka podľa jazyka e-shopu, inak český. Kontakt bez mena meniny nemá. • Spúšťač `trigger_date` s `kind: "name_day"` prejde kontakty e-shopu raz denne v čase `at` (miestny čas firmy). `offsetDays` posunie deň (napríklad `-1` = deň vopred). ## 1. Zásobník kupónov a kódy ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "note": "Sleva 15 % k svátku" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "11", "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "tag": "{{coupon_svatek}}", "note": "Sleva 15 % k svátku", "counts": { "total": 0, "free": 0, "assigned": 0, "used": 0 }, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z" } ``` Kódy vložte ako text, jeden na riadok (duplicitné a neplatné sa preskočia): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks/11/codes" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks/11/codes" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "text": "SVATEK-7Q2K\nSVATEK-9P4M\nSVATEK-3X8D\n" } JSON ``` ```json title="Odpoveď: 200 OK" { "counts": { "added": 3, "duplicate": 0, "invalid": 0, "total": 3 }, "stack": { "id": "11", "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "tag": "{{coupon_svatek}}", "note": "Sleva 15 % k svátku", "counts": { "total": 3, "free": 3, "assigned": 0, "used": 0 }, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z" } } ``` ## 2. Šablóna s kódom `{{ data.promoCode('Svátek') }}` vezme pre každý e-mail nový voľný kód zo zásobníka s **názvom** „Svátek“ z príkladu (to isté robí značka `{{coupon_svatek}}` podľa kľúča). `{{df_salution}}` je oslovenie v 5. páde. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Svátek", "subject": "Všechno nejlepší k svátku, {{df_salution|default('milý zákazníku', true)}}", "preheader": "Dárek k svátku: 15 % sleva", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

k dnešnímu svátku vám přejeme vše nejlepší. Dárkem je sleva 15 % s kódem {{ data.promoCode('Svátek') }}.

Nakoupit se slevou

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "303", "name": "Svátek", "subject": "Všechno nejlepší k svátku, {{df_salution|default('milý zákazníku', true)}}", "preheader": "Dárek k svátku: 15 % sleva", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 425, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [ "subject_long" ], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

k dnešnímu svátku vám přejeme vše nejlepší. Dárkem je sleva 15 % s kódem {{ data.promoCode('Svátek') }}.

Nakoupit se slevou

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/6/2dbee2ba-4435-418f-a8f4-da1f961a9d1a" } ``` > **Pozor:** keď kódy dojdú, e-mail kontaktu neodíde (zlyhanie `customizationDataboxOutOfPromocodes`). Sledujte `counts.free` zásobníka. ## 3. Automatizácia ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Svátek", "shopId": "11", "graph": { "nodes": [ { "id": "svatek", "type": "trigger_date", "config": { "kind": "name_day", "at": "08:00", "reentry": "parallel" } }, { "id": "prani", "type": "send_email", "config": { "templateId": "303" } } ], "edges": [ { "source": "svatek", "target": "prani" } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "83", "name": "Svátek", "shopId": "11", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "svatek", "type": "trigger_date", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "at": "08:00", "kind": "name_day", "reentry": "parallel" } }, { "id": "prani", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "303" } } ], "edges": [ { "source": "svatek", "target": "prani", "branch": "next" } ] }, "issues": [], "triggers": {} } ``` ## 4. Test bez odoslania `POST /automations/{id}/test` ukáže, koľko kontaktov by spúšťač zobral dnes (`scope: "today"`) a koľko by ich došlo do každého uzla. Nič sa neuloží ani neodošle: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/83/test" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/83/test" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' {} JSON ``` ```json title="Odpoveď: 200 OK" { "scope": "today", "days": null, "since": null, "entered": 0, "waiting": 0, "left": 0, "nodes": { "svatek": { "reached": 0, "waiting": 0, "left": 0, "outputs": { "next": 0 } }, "prani": { "reached": 0, "waiting": 0, "left": 0, "outputs": { "next": 0 } } }, "testedAt": "2026-10-01T08:00:00.000Z" } ``` ## 5. Zapnutie a stav kódov ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/83/activate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/83/activate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "83", "name": "Svátek", "shopId": "11", "status": "active", "version": 1, "activeSince": "2026-10-01T08:00:00.000Z", "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "svatek", "type": "trigger_date", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "at": "08:00", "kind": "name_day", "reentry": "parallel" } }, { "id": "prani", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "303" } } ], "edges": [ { "source": "svatek", "target": "prani", "branch": "next" } ] }, "issues": [], "triggers": {} } ``` ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/coupon-stacks/11" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks/11" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "11", "name": "Svátek", "shopId": "11", "mergeKey": "svatek", "tag": "{{coupon_svatek}}", "note": "Sleva 15 % k svátku", "counts": { "total": 3, "free": 3, "assigned": 0, "used": 0 }, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z" } ``` ## Varianty • **Narodeniny:** `kind: "birthday"` (pole `birthday`); 29. februára sa v iných rokoch oslavuje 28. februára. • **Výročie z vlastného poľa:** `kind: "custom_date"`, `field: "cf:"` dátového vlastného poľa. • **Sviatky v kalendári firmy (Vianoce, Deň matiek):** `kind: "holiday"`, `dates: ["12-24"]`; prejde všetky kontakty e-shopu. • **Výročie prvého nákupu:** `kind: "first_order"`, `days: 365`. --- # Recept: návrat neaktívnych zákazníkov **Cieľ:** zákazník, ktorý nenakúpil 120 dní, dostane pripomenutie; keď do týždňa nenakúpi, druhý e-mail s výhodou. Každý zákazník prejde sériou len raz. ## Graf ```text title="Graf" [kazdy-den] trigger_repeat every 1 day, filter: posledná objednávka staršia než 120 dní A aspoň 1 objednávka, reentry once → [email-1] send_email → [tyden] wait 7 days → [nakoupil] condition ordered_since_entry ├─ yes → koniec └─ no → [email-2] send_email [cil] goal: ordered_since_entry (kto nakúpi, opúšťa scenár kdekoľvek) ``` • `trigger_repeat` prejde každý deň (od `startAt`) kontakty e-shopu, ktoré splnia `filter`. Filter je strom pravidiel segmentu a podmienok, ktoré nepotrebujú beh. • `reentry: "once"`: kontakt vstúpi raz a navždy, aj keď filter spĺňa každý deň. • Uzol `goal` nemá hrany; pred každým krokom sa kontroluje, a kto cieľ splní, scenár opúšťa. ## 1. Šablóny ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Win-back 1", "subject": "Chybíte nám", "preheader": "Podívejte se, co je u nás nového", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

dlouho jste u nás nenakoupili. Podívejte se na novinky.

Novinky

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "306", "name": "Win-back 1", "subject": "Chybíte nám", "preheader": "Podívejte se, co je u nás nového", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 346, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

dlouho jste u nás nenakoupili. Podívejte se na novinky.

Novinky

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/11/1e8cfd05-8113-4e6b-9676-ad3dee1e849c" } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Win-back 2", "subject": "Poslední připomenutí", "preheader": "Doprava zdarma jen tento týden", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

tento týden pro vás máme dopravu zdarma.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "307", "name": "Win-back 2", "subject": "Poslední připomenutí", "preheader": "Doprava zdarma jen tento týden", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 273, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

tento týden pro vás máme dopravu zdarma.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/11/8857a9fd-878f-4149-9ad1-55f5c0ae4115" } ``` ## 2. Automatizácia ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Win-back po 120 dnech", "shopId": "21", "graph": { "nodes": [ { "id": "kazdy-den", "type": "trigger_repeat", "config": { "every": { "value": 1, "unit": "days" }, "startAt": "2026-10-02T10:00", "reentry": "once", "filter": { "type": "group", "match": "all", "rules": [ { "type": "last_order", "operator": "older_than_days", "value": "120", "shopId": "21" }, { "type": "order_count", "operator": "gte", "value": "1", "shopId": "21" } ] } } }, { "id": "email-1", "type": "send_email", "config": { "templateId": "306" } }, { "id": "tyden", "type": "wait", "config": { "mode": "duration", "value": 7, "unit": "days" } }, { "id": "nakoupil", "type": "condition", "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "operator": "yes", "shopId": "21" } ] } } }, { "id": "email-2", "type": "send_email", "config": { "templateId": "307" } }, { "id": "cil", "type": "goal", "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "operator": "yes", "shopId": "21" } ] } } } ], "edges": [ { "source": "kazdy-den", "target": "email-1" }, { "source": "email-1", "target": "tyden" }, { "source": "tyden", "target": "nakoupil" }, { "source": "nakoupil", "target": "email-2", "branch": "no" } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "85", "name": "Win-back po 120 dnech", "shopId": "21", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "kazdy-den", "type": "trigger_repeat", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "every": { "unit": "days", "value": 1 }, "filter": { "type": "group", "match": "all", "rules": [ { "type": "last_order", "value": "120", "shopId": "21", "operator": "older_than_days" }, { "type": "order_count", "value": "1", "shopId": "21", "operator": "gte" } ] }, "reentry": "once", "startAt": "2026-10-02T10:00" } }, { "id": "email-1", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "306" } }, { "id": "tyden", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "nakoupil", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } }, { "id": "email-2", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "307" } }, { "id": "cil", "type": "goal", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } } ], "edges": [ { "source": "kazdy-den", "target": "email-1", "branch": "next" }, { "source": "email-1", "target": "tyden", "branch": "next" }, { "source": "tyden", "target": "nakoupil", "branch": "next" }, { "source": "nakoupil", "target": "email-2", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` Detail ukazuje graf, ako ho server uložil (s východiskovými hodnotami) a `issues` (prázdne = dá sa zapnúť): ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/automations/85" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/85" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "85", "name": "Win-back po 120 dnech", "shopId": "21", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "kazdy-den", "type": "trigger_repeat", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "every": { "unit": "days", "value": 1 }, "filter": { "type": "group", "match": "all", "rules": [ { "type": "last_order", "value": "120", "shopId": "21", "operator": "older_than_days" }, { "type": "order_count", "value": "1", "shopId": "21", "operator": "gte" } ] }, "reentry": "once", "startAt": "2026-10-02T10:00" } }, { "id": "email-1", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "306" } }, { "id": "tyden", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "nakoupil", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } }, { "id": "email-2", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "307" } }, { "id": "cil", "type": "goal", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } } ], "edges": [ { "source": "kazdy-den", "target": "email-1", "branch": "next" }, { "source": "email-1", "target": "tyden", "branch": "next" }, { "source": "tyden", "target": "nakoupil", "branch": "next" }, { "source": "nakoupil", "target": "email-2", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` ## 3. Zapnutie, pozastavenie a verzie ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/85/activate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/85/activate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "85", "name": "Win-back po 120 dnech", "shopId": "21", "status": "active", "version": 1, "activeSince": "2026-10-01T08:00:00.000Z", "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "kazdy-den", "type": "trigger_repeat", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "every": { "unit": "days", "value": 1 }, "filter": { "type": "group", "match": "all", "rules": [ { "type": "last_order", "value": "120", "shopId": "21", "operator": "older_than_days" }, { "type": "order_count", "value": "1", "shopId": "21", "operator": "gte" } ] }, "reentry": "once", "startAt": "2026-10-02T10:00" } }, { "id": "email-1", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "306" } }, { "id": "tyden", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "nakoupil", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } }, { "id": "email-2", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "307" } }, { "id": "cil", "type": "goal", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } } ], "edges": [ { "source": "kazdy-den", "target": "email-1", "branch": "next" }, { "source": "email-1", "target": "tyden", "branch": "next" }, { "source": "tyden", "target": "nakoupil", "branch": "next" }, { "source": "nakoupil", "target": "email-2", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` Pozastavenie necháva čakajúce kontakty na mieste; po ďalšom zapnutí pokračujú: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/85/pause" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/85/pause" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "85", "name": "Win-back po 120 dnech", "shopId": "21", "status": "paused", "version": 1, "activeSince": null, "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": "manual", "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "kazdy-den", "type": "trigger_repeat", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "every": { "unit": "days", "value": 1 }, "filter": { "type": "group", "match": "all", "rules": [ { "type": "last_order", "value": "120", "shopId": "21", "operator": "older_than_days" }, { "type": "order_count", "value": "1", "shopId": "21", "operator": "gte" } ] }, "reentry": "once", "startAt": "2026-10-02T10:00" } }, { "id": "email-1", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "306" } }, { "id": "tyden", "type": "wait", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "mode": "duration", "unit": "days", "value": 7 } }, { "id": "nakoupil", "type": "condition", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } }, { "id": "email-2", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "307" } }, { "id": "cil", "type": "goal", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "definition": { "type": "group", "match": "all", "rules": [ { "type": "ordered_since_entry", "shopId": "21", "operator": "yes" } ] } } } ], "edges": [ { "source": "kazdy-den", "target": "email-1", "branch": "next" }, { "source": "email-1", "target": "tyden", "branch": "next" }, { "source": "tyden", "target": "nakoupil", "branch": "next" }, { "source": "nakoupil", "target": "email-2", "branch": "no" } ] }, "issues": [], "triggers": {} } ``` ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/automations/85/versions" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/85/versions" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "version": 1, "status": "draft", "savedAt": "2026-10-01T08:00:00.000Z", "savedBy": "api_key:11", "nodes": 6, "current": true } ] } ``` ## Tipy • Filter spúšťača počíta dni v časovej zóne firmy; `last_order older_than_days 120` znamená „má objednávku a posledná je staršia než 120 dní“. • Pre neotvárajúcich odberateľov (namiesto zákazníkov) použite pravidlo `field` `lastOpenAt` `not_in_last_days` `"180"`. • Odmenu v druhom e-maile dajte jednorazovým kódom (`data.promoCode`), pozrite [recept na meniny](https://www.postarna.sk/docs/api/recipe-name-days). --- # Recept: prihlasovací formulár s potvrdením **Cieľ:** formulár na webe, ktorý po potvrdení e-mailom pridá návštevníka do zoznamu, zapíše súhlas a pošle uvítací e-mail. Toto je správna cesta, keď **nemáte doložený súhlas**: kontakt vznikne ako čakajúci (`pending`) a prihlásený bude až po kliknutí na odkaz v potvrdzovacom e-maile. Cez `POST /contacts` zakladajte len kontakty s už doloženým súhlasom. ## 1. Zoznam pre odberateľov ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/lists" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Newsletter z webu", "publicName": "Novinky e-shopu", "shopId": "5", "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "42", "name": "Newsletter z webu", "publicName": "Novinky e-shopu", "shopId": "5", "systemKind": null, "locked": false, "manualMembers": true, "tags": [], "counts": { "total": 0, "byBucket": { "active": 0, "unconfirmed": 0, "unsubscribed": 0, "bounced": 0, "complained": 0, "blacklisted": 0 } }, "createdAt": "2026-10-01T08:00:00.000Z", "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } ``` ## 2. Formulár `purposeId` je účel spracúvania, ku ktorému sa súhlas zapíše; `consentText` je presné znenie súhlasu, ktoré formulár ukáže a Poštárna uloží k prihláške. `fields` pridá polia okrem e-mailu (`firstName`, `lastName` a ďalšie). ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/forms" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/forms" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Patička webu", "shopId": "5", "status": "active", "fields": [ { "field": "firstName", "required": false } ], "listIds": [ "42" ], "purposeId": "3", "consentText": "Souhlasím se zasíláním obchodních sdělení.", "title": "Odebírejte novinky", "description": "Jednou za měsíc tipy a novinky.", "submitLabel": "Přihlásit", "successUrl": "https://www.example.cz/dekujeme", "confirmedUrl": "https://www.example.cz/potvrzeno" } JSON ``` ```json title="Odpoveď: 201 Created" { "previewUrl": "https://links.example.cz/f/3/50af3dc2-488b-4715-a1b3-3d059af683d8?preview=1", "id": "21", "name": "Patička webu", "shopId": "5", "status": "active", "listIds": [ "42" ], "purposeId": "3", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "kind": "classic", "tags": [], "fills": 0, "publicId": "50af3dc2-488b-4715-a1b3-3d059af683d8", "fields": [ { "label": "", "error": "", "placeholder": "", "field": "email", "required": true }, { "label": "", "error": "", "placeholder": "", "field": "firstName", "required": false } ], "consentText": "Souhlasím se zasíláním obchodních sdělení.", "consentVersion": 1, "title": "Odebírejte novinky", "description": "Jednou za měsíc tipy a novinky.", "submitLabel": "Přihlásit", "successUrl": "https://www.example.cz/dekujeme", "confirmedUrl": "https://www.example.cz/potvrzeno", "captcha": false, "hostedUrl": "https://links.example.cz/f/3/50af3dc2-488b-4715-a1b3-3d059af683d8", "popup": null, "scriptUrl": null, "design": { "template": "classic", "style": "basic-bb2d2d", "width": 320, "image": "", "imagePosition": "top", "showTitle": true, "showText": true, "titleColor": "", "textColor": "", "buttonColor": "", "buttonTextColor": "" }, "settings": { "existingMode": "update", "errorUrl": "", "notify": [], "newTab": false, "keepParams": false, "affiliateParam": "", "thanksHtml": "", "typoCheck": true, "doi": true, "doiTemplateId": null, "senderName": "", "senderEmail": "", "replyTo": "", "doiAfter": "thanks", "doiThanksHtml": "", "consentMode": "checkbox", "consentLabel": "", "consentLinkText": "", "consentLinkUrl": "", "extraPurposes": [] } } ``` • `successUrl`: kam formulár presmeruje po odoslaní; `confirmedUrl`: kam vedie potvrdzovací odkaz. • Formulár je v východiskovom nastavení double opt-in. Potvrdzovací e-mail je systémový (bez obchodného obsahu a pätičky), odchádza od odosielateľa formulára (`settings.senderEmail`), inak od overeného východiskového odosielateľa e-shopu, a najviac 3-krát za deň na jednu adresu. • `previewUrl` je náhľad formulára, `publicId` jeho verejné ID. ## 3. Kód pre web ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/forms/21/embed" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/forms/21/embed" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "html": "\n
\n
\n
\n

\n
\n \n

Example s.r.o., Ukázková 1, 110 00 Praha 1 Zásady ochrany osobních údajů

\n
\n", "styled": "\n

Odebírejte novinky

Jednou za měsíc tipy a novinky.

Example s.r.o., Ukázková 1, 110 00 Praha 1 Zásady ochrany osobních údajů

\n", "url": "https://links.example.cz/f/3/50af3dc2-488b-4715-a1b3-3d059af683d8", "script": "" } ``` Vložte `html` na web. Formulár posiela dáta na odkazovú doménu e-shopu (`/f//`); stránky po odoslaní a potvrdení vykresľuje Poštárna. • Ochrana proti robotom: skryté pole (vyplnené = tichý úspech bez zápisu), voliteľne captcha. • Limity: 10 odoslaní za hodinu z jednej IP adresy na formulár, 3 za deň na jednu e-mailovú adresu, 300 za hodinu na firmu (429). • Pre každú adresu je odpoveď rovnaká, takže formulár neprezradí, kto už je v databáze. ## 4. Čo sa stane po odoslaní 1. Kontakt vznikne (alebo sa nájde) v stave `pending`, členstvo v zoznamoch je `unconfirmed`, zapíše sa žiadosť o súhlas s IP adresou, prehliadačom, stránkou a presným textom súhlasu. 2. Odíde potvrdzovací e-mail. Odkaz platí 7 dní. 3. Po kliknutí: kontakt `subscribed` (`consentBasis: "double_opt_in"`), členstvo `confirmed`, súhlas s účelom formulára, vyplnené polia formulára sa uložia do kontaktu, presmerovanie na `confirmedUrl`. 4. Odhlásený kontakt sa tak znovu prihlási; nedoručiteľná adresa alebo sťažnosť nedostane nič. ## 5. Uvítací e-mail po potvrdení Spúšťač `form_submitted` s `formId` pustí kontakt do scenára, hneď ako potvrdí odber (nepotvrdený kontakt e-maily nedostáva): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/templates" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Uvítání", "subject": "Vítejte mezi odběrateli", "preheader": "Děkujeme za potvrzení odběru", "content": { "editor": "html", "design": null, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

děkujeme za potvrzení odběru.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "302", "name": "Uvítání", "subject": "Vítejte mezi odběrateli", "preheader": "Děkujeme za potvrzení odběru", "editor": "html", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "tags": [], "size": 262, "archived": false, "archivedAt": null, "readOnly": false, "usage": { "campaigns": 0, "automations": 0 }, "lastUsedAt": null, "check": { "errors": [], "warnings": [], "checkedAt": "2026-10-01T08:00:00.000Z" }, "content": { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

děkujeme za potvrzení odběru.

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" }, "settings": { "linkParams": [], "headers": [], "unsubscribePageId": null, "footerId": null }, "draft": { "pending": false, "savedAt": null, "publishedAt": null }, "activeUses": { "automations": 0, "emails": 0, "campaigns": 0 }, "publicUrl": "https://links.example.cz/template/3/e2ad6880-3f53-4fc1-988d-a4893a6ab8a3" } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Uvítání z formuláře", "shopId": "5", "graph": { "nodes": [ { "id": "formular", "type": "trigger_event", "config": { "event": "form_submitted", "formId": "21", "reentry": "once" } }, { "id": "uvitani", "type": "send_email", "config": { "templateId": "302" } } ], "edges": [ { "source": "formular", "target": "uvitani" } ] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "82", "name": "Uvítání z formuláře", "shopId": "5", "status": "draft", "version": 1, "activeSince": null, "firstActivatedAt": null, "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "formular", "type": "trigger_event", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "form_submitted", "formId": "21", "reentry": "once" } }, { "id": "uvitani", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "302" } } ], "edges": [ { "source": "formular", "target": "uvitani", "branch": "next" } ] }, "issues": [], "triggers": {} } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/automations/82/activate" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/82/activate" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "82", "name": "Uvítání z formuláře", "shopId": "5", "status": "active", "version": 1, "activeSince": "2026-10-01T08:00:00.000Z", "firstActivatedAt": "2026-10-01T08:00:00.000Z", "pausedReason": null, "tags": [], "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": { "entered": 0, "active": 0, "sent": 0 }, "description": "", "graph": { "nodes": [ { "id": "formular", "type": "trigger_event", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "event": "form_submitted", "formId": "21", "reentry": "once" } }, { "id": "uvitani", "type": "send_email", "name": "", "note": "", "position": { "x": 0, "y": 0 }, "config": { "templateId": "302" } } ], "edges": [ { "source": "formular", "target": "uvitani", "branch": "next" } ] }, "issues": [], "triggers": {} } ``` ## Varianty • **Vlastný formulár na webe:** postavte vlastné HTML a posielajte rovnaké polia na adresu `action` z kódu formulára (`email`, polia formulára, súhlasy). Nevolajte na to `POST /contacts`, to je len pre doložené súhlasy. • **Prihlásenie odkiaľkoľvek:** namiesto `form_submitted` použite `subscribed` so `sources: ["signup_form"]`. • **Pop-up:** formulár s `kind: "popup"` a nastavením `popup` (polia popísané v [skupine Formuláre](https://www.postarna.sk/docs/api/reference-forms)). --- # Recept: import kontaktov z CSV **Cieľ:** nahrať kontakty z CSV súboru so súhlasom, ktorý máte doložený, a overiť výsledok. **Potrebujete:** kľúč s modulom `contacts` na úrovni `full`. ## 1. Nahranie súboru Dve možnosti: • `multipart/form-data` s poľom `file` (súbor do 64 MB a 300 000 riadkov, kódovanie UTF-8, UTF-16 alebo windows-1250 sa pozná samo) a voliteľne `delimiter`, `quote`, `hasHeader`, `encoding`. • JSON `{"text": "...", "delimiter", "quote", "hasHeader"}` s obsahom do 5 MB. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/imports/files" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/imports/files" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "text": "email;jmeno;prijmeni;mesto\nmarie.dvorakova@example.cz;Marie;Dvořáková;Praha\ntomas.cerny@example.cz;Tomáš;Černý;Ostrava\nchybna-adresa;Jan;Bez;Plzeň\n", "delimiter": ";", "quote": "\"", "hasHeader": true } JSON ``` ```json title="Odpoveď: 201 Created" { "fileId": "71", "fileName": "vlozeny-text.csv", "size": 155, "delimiter": ";", "quote": "\"", "hasHeader": true, "encoding": "utf-8", "columns": [ "email", "jmeno", "prijmeni", "mesto" ], "rowCount": 3, "sample": [ [ "marie.dvorakova@example.cz", "Marie", "Dvořáková", "Praha" ], [ "tomas.cerny@example.cz", "Tomáš", "Černý", "Ostrava" ], [ "chybna-adresa", "Jan", "Bez", "Plzeň" ] ], "suggestedKind": "csv", "suggestedMapping": [ "email", "firstName", "lastName", "city" ] } ``` Odpoveď má `fileId`, rozpoznané stĺpce, ukázku riadkov a `suggestedMapping` (návrh, ktoré pole je v ktorom stĺpci). Súbor sa drží 24 hodín. ## 2. Náhľad `mapping` má jednu položku na stĺpec súboru, v poradí: názov poľa, alebo `null` (stĺpec preskočiť). Práve jeden stĺpec musí byť `email`. Polia: `email`, `firstName`, `lastName`, `fullName`, `titleBefore`, `titleAfter`, `phone`, `mobile`, `company`, `companyId`, `street`, `city`, `postalCode`, `country`, `language`, `gender`, `birthday`, `note`, `newsletterConsent`, `newsletterConsentAt`, `registeredAt` a vlastné pole. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/imports/preview" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/imports/preview" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "fileId": "71", "mapping": [ "email", "firstName", "lastName", "city" ], "mode": "upsert", "shopId": "9", "listIds": [] } JSON ``` ```json title="Odpoveď: 200 OK" { "counts": { "rows": 3, "create": 2, "update": 0, "skipSuppressed": 0, "skipMissing": 0, "invalid": 1, "duplicate": 0, "unsubscribe": 0, "remove": 0, "blacklist": 0 }, "rows": [ { "row": 2, "email": "marie.dvorakova@example.cz", "action": "create", "error": null, "field": null, "values": { "email": "marie.dvorakova@example.cz", "firstName": "Marie", "lastName": "Dvořáková", "city": "Praha" }, "consent": true }, { "row": 3, "email": "tomas.cerny@example.cz", "action": "create", "error": null, "field": null, "values": { "email": "tomas.cerny@example.cz", "firstName": "Tomáš", "lastName": "Černý", "city": "Ostrava" }, "consent": true }, { "row": 4, "email": "chybna-adresa", "action": "invalid", "error": "email_invalid", "field": "email", "values": { "email": "chybna-adresa", "firstName": "Jan", "lastName": "Bez", "city": "Plzeň" }, "consent": null } ], "report": { "consent": { "optIn": 2, "none": 0, "keptUnsubscribed": 0 }, "merge": { "existing": 0, "fromSources": {}, "fieldsUpdated": 0, "fieldsKeptEdited": 0 }, "dropped": {} } } ``` `counts` hovorí, koľko riadkov sa založí, aktualizuje, preskočí (potlačené adresy, chyby) a prečo; `rows` ukazuje prvé riadky s ich výsledkom. ## 3. Spustenie • `mode`: `upsert` (založiť aj aktualizovať), `update_only`, alebo hromadné odhlásenie `unsubscribe`, odobratie `remove`, blacklist `blacklist`. • `purposeId` a `consentConfirmed: true`: potvrdzujete, že ku všetkým kontaktom máte doložený súhlas s týmto účelom (pri `unsubscribe`, `remove` a `blacklist` súhlas potrebný nie je). • `listIds`: ručné zoznamy, do ktorých kontakty pribudnú. • `runAutomations`: východiskovo `false` = import nespustí žiadnu automatizáciu (ani „nový kontakt“ či „pridanie do zoznamu“). Zapnite len vedome. • `kind`: `csv`, alebo exporty Shoptetu `shoptet_customers` a `shoptet_newsletter`. ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/imports" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/imports" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Kontakty z veletrhu", "source": "csv", "fileId": "71", "mapping": [ "email", "firstName", "lastName", "city" ], "mode": "upsert", "shopId": "9", "listIds": [], "purposeId": "5", "consentConfirmed": true } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "61", "name": "Kontakty z veletrhu", "status": "finished", "kind": "csv", "fileName": "vlozeny-text.csv", "shopId": "9", "mode": "upsert", "listIds": [], "createdAt": "2026-10-01T08:00:00.000Z", "startedAt": "2026-10-01T08:00:00.000Z", "finishedAt": "2026-10-01T08:00:00.000Z", "progress": { "processed": 3, "total": 3 }, "counts": { "rows": 3, "create": 2, "remove": 0, "update": 0, "invalid": 1, "blacklist": 0, "duplicate": 0, "skipMissing": 0, "unsubscribe": 0, "skipSuppressed": 0 }, "source": "csv", "purposeId": "5", "addedToLists": 0, "errors": [ { "row": 4, "error": "email_invalid", "field": "email" } ], "runAutomations": false, "options": {}, "report": { "consent": { "none": 0, "optIn": 2, "keptUnsubscribed": 0 }, "merge": { "existing": 0, "fromSources": {}, "fieldsUpdated": 0, "fieldsKeptEdited": 0 }, "dropped": {} } } ``` Do 1 000 riadkov prebehne import hneď (`status: "finished"`); väčší ide do radu (`queued`, `running` s priebehom `progress`) a dokončí ho worker. ## 4. Výsledok ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/imports/61" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/imports/61" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "61", "name": "Kontakty z veletrhu", "status": "finished", "kind": "csv", "fileName": "vlozeny-text.csv", "shopId": "9", "mode": "upsert", "listIds": [], "createdAt": "2026-10-01T08:00:00.000Z", "startedAt": "2026-10-01T08:00:00.000Z", "finishedAt": "2026-10-01T08:00:00.000Z", "progress": { "processed": 3, "total": 3 }, "counts": { "rows": 3, "create": 2, "remove": 0, "update": 0, "invalid": 1, "blacklist": 0, "duplicate": 0, "skipMissing": 0, "unsubscribe": 0, "skipSuppressed": 0 }, "source": "csv", "purposeId": "5", "addedToLists": 0, "errors": [ { "row": 4, "error": "email_invalid", "field": "email" } ], "runAutomations": false, "options": {}, "report": { "consent": { "none": 0, "optIn": 2, "keptUnsubscribed": 0 }, "merge": { "existing": 0, "fromSources": {}, "fieldsUpdated": 0, "fieldsKeptEdited": 0 }, "dropped": {} } } ``` `errors` uvádza riadky, ktoré neprešli (tu neplatná adresa na riadku 4). ## Pravidlá, na ktoré pozor • **Potlačená adresa** (odhlásená, nedoručiteľná, sťažnosť) sa importom nikdy znovu neprihlási. • Polia, ktoré v aplikácii upravil človek, import neprepíše. • Adresa vymazaná na žiadosť (GDPR) sa importom znovu nezaloží. • Import zákazníkov bez súhlasu (`shoptet_customers` bez stĺpca súhlasu) založí kontakty `customer`, ktorým sa nepíše. --- # Recept: odoslanie kampane **Cieľ:** pripraviť newsletter pre zoznam odberateľov, skontrolovať obsah a príjemcov, poslať test a naplánovať odoslanie. **Potrebujete:** kľúč s rolou `marketing_manager`, overeného odosielateľa, testovaciu adresu firmy (v aplikácii Testovacie adresy v nastavení odosielania; cez API `PUT /test-recipients` s rolou správcu účtu). ## 1. Príjemcovia Na ukázku kontakt so súhlasom a zoznam: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "email": "petr.svoboda@example.cz", "shopId": "17", "purposeId": "9", "consentConfirmed": true, "firstName": "Petr", "vocativeFirstName": "Petře" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "1206", "email": "petr.svoboda@example.cz", "firstName": "Petr", "lastName": "", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "17", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "Petře", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": null, "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-7", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/lists" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Newsletter", "publicName": "Novinky e-shopu", "shopId": "17", "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "44", "name": "Newsletter", "publicName": "Novinky e-shopu", "shopId": "17", "systemKind": null, "locked": false, "manualMembers": true, "tags": [], "counts": { "total": 0, "byBucket": { "active": 0, "unconfirmed": 0, "unsubscribed": 0, "bounced": 0, "complained": 0, "blacklisted": 0 } }, "createdAt": "2026-10-01T08:00:00.000Z", "notifyOnUnsubscribe": false, "notifyOnAdd": false, "note": "" } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/lists/44/members" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists/44/members" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "contactIds": [ "1206" ] } JSON ``` ```json title="Odpoveď: 200 OK" { "added": 1, "alreadyMember": 0, "skipped": 0 } ``` ## 2. Odosielateľ ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/senders" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/senders" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "items": [ { "id": "17", "shopId": "17", "name": "Example.cz", "email": "info@example.cz", "replyTo": "", "verified": true, "isDefault": true }, { "id": "18", "shopId": "18", "name": "Example.sk", "email": "info@example.sk", "replyTo": "", "verified": true, "isDefault": true } ] } ``` Odosielať smie len overená adresa (`verified: true`) e-shopu kampane. ## 3. Koncept kampane ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Říjnový newsletter", "shopId": "17", "senderId": "17", "fromName": "Example.cz", "subject": "Podzimní novinky", "preheader": "Nová káva a tipy na přípravu", "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] } } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "151", "name": "Říjnový newsletter", "shopId": "17", "subject": "Podzimní novinky", "status": "draft", "recipients": null, "scheduledAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": null, "variantGroupId": null, "variantLabel": "", "variantPosition": 0, "tags": [], "preheader": "Nová káva a tipy na přípravu", "senderId": "17", "fromName": "Example.cz", "fromEmail": "info@example.cz", "replyTo": "", "templateId": null, "hasContent": false, "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] }, "pausedReason": null, "approvedAt": null, "trackOpens": true, "trackClicks": true, "utm": null, "headers": [], "timing": "later", "plannedAt": null, "linkParams": [], "preferTime": false, "replyToOptions": [ "info@example.cz" ] } ``` ## 4. Obsah `baseVersion: 0` pri kampani, ktorá obsah ešte nemá. Obsah musí mať odkaz na odhlásenie (`{{unsubscribe}}`), inak Poštárna doplní štandardnú pätičku. ```bash title="Požiadavka: PUT /api/v1/tenants/{tenant}/campaigns/151/content" curl -sS -X PUT "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/content" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "editor": "html", "design": null, "baseVersion": 0, "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

na e-shopu máme novou podzimní kávu.

Prohlédnout novinky

{{cl_company}}, {{cl_address}}. Odhlásit odběr

" } JSON ``` ```json title="Odpoveď: 200 OK" { "editor": "html", "html": "

Dobrý den, {{df_salution|default('vážený zákazníku', true)}},

na e-shopu máme novou podzimní kávu.

Prohlédnout novinky

{{cl_company}}, {{cl_address}}. Odhlásit odběr

", "design": null, "version": 1, "updatedAt": "2026-10-01T08:00:00.000Z" } ``` Kontrola obsahu (tu s neznámou značkou a bez odhlásenia): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/content/lint" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/content/lint" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "html": "

Dobrý den, {{df_jmeno}}

", "subject": "Podzimní novinky", "preheader": "" } JSON ``` ```json title="Odpoveď: 200 OK" { "issues": [ { "code": "unknown_tag", "severity": "error", "params": { "tags": "{{df_jmeno}}" } }, { "code": "no_unsubscribe", "severity": "warning", "params": {} } ] } ``` ## 5. Počet príjemcov ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/audience" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/audience" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "shopId": "17", "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] } } JSON ``` ```json title="Odpoveď: 200 OK" { "matched": 1, "recipients": 1, "excluded": { "not_mailable": 0, "unconfirmed": 0, "weak_consent": 0, "exception_expired": 0, "no_purpose": 0, "excluded_list": 0, "excluded_manual": 0, "inactive": 0 } } ``` ## 6. Testovací e-mail Len na testovacie adresy firmy (`GET /test-recipients`), najviac 10 za 24 hodín: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/test" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/test" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "to": "test@example.cz" } JSON ``` ```json title="Odpoveď: 200 OK" { "to": "test@example.cz", "sentAt": "2026-10-01T08:00:00.000Z" } ``` ## 7. Schválenie > **Pozor:** schválenie posiela e-maily skutočným ľuďom. Ukážte človeku predmet, odosielateľa, čas a počet príjemcov (z kroku 5) a pošlite ho ako `expectedRecipients` až po jeho potvrdení. Keď počet nesedí (líši sa o viac než 5 %), kampaň zostane konceptom: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/approve" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/approve" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "sendAt": "2026-10-02T07:00:00.000Z", "expectedRecipients": 250 } JSON ``` ```json title="Odpoveď: 409 Conflict" { "error": { "code": "conflict", "message": "recipients", "params": { "expected": 250, "actual": 1 } } } ``` So správnym počtom a časom odoslania (`sendAt` 5 minút až 365 dní dopredu, `null` = hneď): ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/approve" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/approve" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "sendAt": "2026-10-02T07:00:00.000Z", "expectedRecipients": 1 } JSON ``` ```json title="Odpoveď: 200 OK" { "id": "151", "name": "Říjnový newsletter", "shopId": "17", "subject": "Podzimní novinky", "status": "scheduled", "recipients": 1, "scheduledAt": "2026-10-02T07:00:00.000Z", "startedAt": null, "completedAt": null, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": null, "variantGroupId": null, "variantLabel": "", "variantPosition": 0, "tags": [], "preheader": "Nová káva a tipy na přípravu", "senderId": "17", "fromName": "Example.cz", "fromEmail": "info@example.cz", "replyTo": "", "templateId": null, "hasContent": true, "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] }, "pausedReason": null, "approvedAt": "2026-10-01T08:00:00.000Z", "trackOpens": true, "trackClicks": true, "utm": null, "headers": [], "timing": "later", "plannedAt": null, "linkParams": [], "preferTime": false, "replyToOptions": [ "info@example.cz" ] } ``` ```bash title="Požiadavka: GET /api/v1/tenants/{tenant}/campaigns/151" curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "151", "name": "Říjnový newsletter", "shopId": "17", "subject": "Podzimní novinky", "status": "scheduled", "recipients": 1, "scheduledAt": "2026-10-02T07:00:00.000Z", "startedAt": null, "completedAt": null, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": null, "variantGroupId": null, "variantLabel": "", "variantPosition": 0, "tags": [], "preheader": "Nová káva a tipy na přípravu", "senderId": "17", "fromName": "Example.cz", "fromEmail": "info@example.cz", "replyTo": "", "templateId": null, "hasContent": true, "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] }, "pausedReason": null, "approvedAt": "2026-10-01T08:00:00.000Z", "trackOpens": true, "trackClicks": true, "utm": null, "headers": [], "timing": "later", "plannedAt": null, "linkParams": [], "preferTime": false, "replyToOptions": [ "info@example.cz" ] } ``` ## 8. Pauza a zrušenie Naplánovanú alebo odosielanú kampaň zastaví `POST /campaigns/{id}/pause`, znovu ju pustí `/resume`, úplne zruší `/cancel`: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/cancel" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/cancel" \ -H "Authorization: Bearer $POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "id": "151", "name": "Říjnový newsletter", "shopId": "17", "subject": "Podzimní novinky", "status": "cancelled", "recipients": 1, "scheduledAt": "2026-10-02T07:00:00.000Z", "startedAt": null, "completedAt": null, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "stats": null, "variantGroupId": null, "variantLabel": "", "variantPosition": 0, "tags": [], "preheader": "Nová káva a tipy na přípravu", "senderId": "17", "fromName": "Example.cz", "fromEmail": "info@example.cz", "replyTo": "", "templateId": null, "hasContent": true, "audience": { "listIds": [ "44" ], "segmentIds": [], "excludeListIds": [], "excludeInactive": true, "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": [] }, "pausedReason": null, "approvedAt": "2026-10-01T08:00:00.000Z", "trackOpens": true, "trackClicks": true, "utm": null, "headers": [], "timing": "later", "plannedAt": null, "linkParams": [], "preferTime": false, "replyToOptions": [ "info@example.cz" ] } ``` ## Štatistiky po odoslaní `GET /campaigns/{id}` (`stats`), `GET /stats/campaigns/{id}`, `/recipients?format=csv`, `/conversions`. Pozrite [Kampane](https://www.postarna.sk/docs/api/campaigns#statistiky). --- # Recept: príjem webhookov **Cieľ:** udržať CRM v súlade s Poštárnou: nové kontakty založiť, odhlásené označiť. **Potrebujete:** kľúč s rolou `account_admin` (webhooky sú v module `settings`), e-mail člena firmy pre HTTP Basic, verejnú adresu `https://` vášho príjemcu. ## 1. Registrácia ```bash title="Požiadavka: POST /api/v3/web-hooks" curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "target_url": "https://crm.example.cz/postarna/webhook", "event": "new_contact", "basic_auth": { "login": "postarna", "password": "example-webhook-password" } } JSON ``` ```json title="Odpoveď: 201 Created" { "status": "created", "meta": [], "id": 7 } ``` ```bash title="Požiadavka: POST /api/v3/web-hooks" curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "target_url": "https://crm.example.cz/postarna/webhook", "event": "unsubscribed_contact", "basic_auth": { "login": "postarna", "password": "example-webhook-password" } } JSON ``` ```json title="Odpoveď: 201 Created" { "status": "created", "meta": [], "id": 8 } ``` Heslo `basic_auth` si vygenerujte náhodne (aspoň 32 znakov) a uložte do premennej prostredia príjemcu. ## 2. Čo prijde Po založení a odhlásení kontaktu prídu dve volania: ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "email": "eva.horakova@example.cz", "shopId": "19", "purposeId": "10", "consentConfirmed": true, "firstName": "Eva", "lastName": "Horáková" } JSON ``` ```json title="Odpoveď: 201 Created" { "id": "1207", "email": "eva.horakova@example.cz", "firstName": "Eva", "lastName": "Horáková", "status": "subscribed", "engagement": "N", "excluded": false, "shopId": "19", "suppressionReason": null, "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": null, "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-8", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` ```bash title="Požiadavka: POST /api/v1/tenants/{tenant}/contacts/1207/unsubscribe" curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts/1207/unsubscribe" \ -H "Authorization: Bearer $POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "note": "Odhlášení z CRM" } JSON ``` ```json title="Odpoveď: 200 OK" { "id": "1207", "email": "eva.horakova@example.cz", "firstName": "Eva", "lastName": "Horáková", "status": "unsubscribed", "engagement": "N", "excluded": false, "shopId": "19", "suppressionReason": "unsubscribed", "blacklisted": false, "blacklistedAt": null, "state": null, "createdAt": "2026-10-01T08:00:00.000Z", "phone": "", "mobile": "", "titleBefore": "", "titleAfter": "", "salutation": "", "salutationFormal": "", "vocativeFirstName": "", "vocativeLastName": "", "gender": null, "language": "cs", "company": "", "companyId": "", "street": "", "city": "", "postalCode": "", "note": "", "affiliateId": "", "country": null, "birthday": null, "nameDay": null, "source": "manual", "consentBasis": "imported", "statusAt": "2026-10-01T08:00:00.000Z", "consentAt": "2026-10-01T08:00:00.000Z", "consentWeak": false, "softBounces": 0, "lastSentAt": null, "lastOpenAt": null, "lastClickAt": null, "suppressedAt": "2026-10-01T08:00:00.000Z", "engagementAt": null, "suppressionNote": null, "customFields": {}, "updatedAt": "2026-10-01T08:00:00.000Z", "stats90d": { "received": 0, "opened": 0, "clicked": 0, "bestHour": null }, "lists": [], "recentActivities": [ { "id": "consent-9", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "suppressed" }, { "id": "consent-8", "type": "status_change", "at": "2026-10-01T08:00:00.000Z", "title": "purpose_assigned" }, { "id": "consent-10", "type": "unsubscribed", "at": "2026-10-01T08:00:00.000Z", "title": "admin" } ], "orders": [], "orderTotals": [], "editedFields": [], "sources": [] } ``` ```json title="Webhook doručí (POST na vašu adresu): new_contact" [ { "id": 1207, "guid": null, "emailaddress": "eva.horakova@example.cz", "domain": "example.cz", "name": "Eva", "surname": "Horáková", "titlesbefore": null, "titlesafter": null, "salution": null, "company": null, "street": null, "town": null, "postalcode": null, "country": null, "cellphone": null, "phone": null, "language": "cs_CZ", "birthday": null, "nameday": null, "gender": null, "notes": null, "realname": "Eva Horáková", "blacklisted": 0, "is_blacklisted": false, "hardbounced": 0, "softbounced": 0, "created": "2026-10-01 10:00:00", "updated": "2026-10-01 10:00:00", "created_at": "2026-10-01 10:00:00", "last_updated_at": "2026-10-01 10:00:00", "origin": "manual", "contactlists": [], "customfields": [], "event": "new_contact" } ] ``` ```json title="Webhook doručí (POST na vašu adresu): unsubscribed_contact" [ { "id": 1207, "guid": null, "emailaddress": "eva.horakova@example.cz", "domain": "example.cz", "name": "Eva", "surname": "Horáková", "titlesbefore": null, "titlesafter": null, "salution": null, "company": null, "street": null, "town": null, "postalcode": null, "country": null, "cellphone": null, "phone": null, "language": "cs_CZ", "birthday": null, "nameday": null, "gender": null, "notes": null, "realname": "Eva Horáková", "blacklisted": 0, "is_blacklisted": false, "hardbounced": 0, "softbounced": 0, "created": "2026-10-01 10:00:00", "updated": "2026-10-01 10:00:00", "created_at": "2026-10-01 10:00:00", "last_updated_at": "2026-10-01 10:00:00", "origin": "manual", "contactlists": [], "customfields": [], "event": "unsubscribed_contact", "reason": "admin", "unsubscribed_contactlist_ids": [], "campaign_type": null, "campaign_id": null, "email_statistic_id": null, "trigger_event": null } ] ``` ## 3. Príjemca v Pythone (Flask) ```python title="app.py" import hmac import os from flask import Flask, abort, request app = Flask(__name__) USER = os.environ['POSTARNA_HOOK_USER'] # login z basic_auth PASSWORD = os.environ['POSTARNA_HOOK_PASSWORD'] # heslo z basic_auth def authorized(): auth = request.authorization return bool(auth) and hmac.compare_digest(auth.username or '', USER) \ and hmac.compare_digest(auth.password or '', PASSWORD) @app.post('/postarna/webhook') def postarna_webhook(): if not authorized(): abort(401) payload = request.get_json(silent=True) items = payload if isinstance(payload, list) else [payload] for item in items: event = item.get('event') if event == 'new_contact': crm_upsert_contact(email=item['emailaddress'], first_name=item.get('name'), last_name=item.get('surname')) elif event == 'unsubscribed_contact': crm_mark_unsubscribed(email=item['emailaddress'], reason=item.get('reason')) return '', 204 # 2xx do 30 s, inak prijde znovu def crm_upsert_contact(email, first_name, last_name): ... # založiť alebo upraviť podľa e-mailu (opakované doručenie neprekáža) def crm_mark_unsubscribed(email, reason): ... # nastaviť príznak (opakované doručenie neprekáža) ``` ## 4. Príjemca v Node.js (Express) ```javascript title="server.js" import crypto from 'node:crypto'; import express from 'express'; const app = express(); app.use(express.json({ limit: '1mb' })); const USER = process.env.POSTARNA_HOOK_USER; const PASSWORD = process.env.POSTARNA_HOOK_PASSWORD; function same(a, b) { const x = Buffer.from(a ?? ''); const y = Buffer.from(b ?? ''); return x.length === y.length && crypto.timingSafeEqual(x, y); } function authorized(req) { const [scheme, value] = (req.get('Authorization') ?? '').split(' '); if (scheme !== 'Basic' || !value) return false; const [user, ...rest] = Buffer.from(value, 'base64').toString('utf8').split(':'); return same(user, USER) && same(rest.join(':'), PASSWORD); } app.post('/postarna/webhook', async (req, res) => { if (!authorized(req)) return res.sendStatus(401); const items = Array.isArray(req.body) ? req.body : [req.body]; for (const item of items) { if (item.event === 'new_contact') await crmUpsertContact(item.emailaddress, item.name, item.surname); if (item.event === 'unsubscribed_contact') await crmMarkUnsubscribed(item.emailaddress, item.reason); } res.sendStatus(204); // 2xx do 30 s, inak prijde znovu }); app.listen(8080); ``` ## 5. Pravidlá dobrého príjemcu • **Odpovedajte rýchlo**: dlhšie spracovanie dajte do radu a hneď vráťte 2xx. Po 30 sekundách sa volanie počíta ako chyba. • **Zvládnete opakovanie**: rovnaká položka môže prísť viackrát. Spracovanie robte idempotentné (upsert podľa e-mailu, nastavenie príznaku), pri e-mailových udalostiach si pamätajte `id`. • **Neodpovedajte chybou na neznámu udalosť**: vráťte 2xx, inak sa webhook po 10 chybách vypne. • **Sledujte stav**: `GET /api/v3/web-hooks` ukazuje `active`, `last_response_code`, `last_call_time` a `errors_in_row`. • Odhlásenie v CRM pošlite späť do Poštárne cez `POST /api/v1/tenants/{tenant}/contacts/{id}/unsubscribe`, aby obe strany držali rovnaký stav. --- # Webhooky Poštárna vie posielať dva druhy webhookov: | | Účtový webhook | Uzol `webhook` v automatizácii | |---|---|---| | Kedy volá | pri udalosti vo firme (nový kontakt, odhlásenie, doručenie ...) | keď kontakt dojde v automatizácii na uzol | | Registrácia | `POST /api/v3/web-hooks` (kompatibilné so SmartEmailingom) | v grafe automatizácie | | Tvar dát | pevný, ako SmartEmailing | vlastné telo so zástupnými značkami | | Opakovanie | pri ďalšom behu (každých ~30 s), po 10 chybách v rade sa vypne | 5 pokusov po 5 minútach | ## Účtové webhooky ### Udalosti | `event` | Kedy | Telo | |---|---|---| | `new_contact` | nový kontakt | pole s jedným kontaktom | | `updated_contact` | zmena kontaktu | pole s jedným kontaktom | | `unsubscribed_contact` | odhlásenie (zo všetkého alebo zo zoznamu) | pole s jedným kontaktom a dôvodom | | `sent_email` | e-mail odoslaný | objekt | | `delivery_status` | doručené, mäkko alebo tvrdo vrátené (s odpoveďou servera) | objekt | | `email_open` | otvorenie (len ľudia, strojové otvorenia sa nepočítajú) | objekt | | `email_click` | klik (len ľudia) | objekt | | `email_delivery_started`, `scoring_result_changed`, `engagement_level_changed`, `sms_delivery_status` | prijmú sa pre kompatibilitu, **zatiaľ sa nikdy nevolajú** | | ### Registrácia Prihlásenie ako pri API v3: HTTP Basic (e-mail člena firmy a API kľúč) alebo Bearer. Kľúč potrebuje modul `settings` na úrovni `full` (rola správcu účtu). ```bash title="Požiadavka: POST /api/v3/web-hooks" curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "target_url": "https://crm.example.cz/postarna/webhook", "event": "new_contact", "basic_auth": { "login": "postarna", "password": "example-webhook-password" } } JSON ``` ```json title="Odpoveď: 201 Created" { "status": "created", "meta": [], "id": 7 } ``` • `target_url`: adresa `http://` alebo `https://`, najviac 1 000 znakov. Volať sa dajú len verejné adresy (nie interné siete), presmerovania sa nesledujú. • `basic_auth` `{login, password}` (nepovinné): Poštárna ho pošle v hlavičke `Authorization: Basic`. Heslo sa ukladá šifrovane a nikdy sa nevracia (`***`). • Rovnaká adresa pre rovnakú udalosť druhýkrát = 409 `Already exists`; najviac 50 webhookov na firmu. • Nový webhook začína od najnovšieho záznamu: posiela len to, čo sa stane po registrácii. ```bash title="Požiadavka: POST /api/v3/web-hooks" curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "target_url": "https://crm.example.cz/postarna/webhook", "event": "new_contact" } JSON ``` ```json title="Odpoveď: 409 Conflict" { "status": "error", "meta": [], "message": "Already exists" } ``` ```bash title="Požiadavka: GET /api/v3/web-hooks" curl -sS -X GET "https://www.postarna.cz/api/v3/web-hooks" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "status": "ok", "meta": { "total_count": 2, "displayed_count": 2, "offset": 0, "limit": 500 }, "data": [ { "id": 7, "url": "https://crm.example.cz/postarna/webhook", "method": "POST", "event": "new_contact", "active": 1, "timeout": 30, "last_response_code": null, "last_call_time": null, "errors_in_row": 0, "basic_auth": { "login": "***", "password": "***" } }, { "id": 8, "url": "https://crm.example.cz/postarna/webhook", "method": "POST", "event": "unsubscribed_contact", "active": 1, "timeout": 30, "last_response_code": null, "last_call_time": null, "errors_in_row": 0, "basic_auth": { "login": "***", "password": "***" } } ] } ``` Cez API v3 sa webhook upraviť nedá (rovnako ako v SmartEmailingu); zmažte ho a zaregistrujte znovu. V aplikácii v Nastaveniach › Dátové zdroje › Webhooky ho upravíte, vypnete, znova zapnete aj otestujete (API v1 `PATCH` a `POST …/test` na `/tenants/{tenant}/account-webhooks`): ```bash title="Požiadavka: DELETE /api/v3/web-hooks/7" curl -sS -X DELETE "https://www.postarna.cz/api/v3/web-hooks/7" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" ``` ```text title="Odpoveď: 204 No Content" (bez tela) ``` ### Tvar dát Každá položka je jeden POST s `Content-Type: application/json` a `User-Agent: Postarna-Webhook/1`. Kontaktové udalosti posielajú **pole s jedným kontaktom** v tvare API v3 SmartEmailingu (časy `YYYY-MM-DD HH:MM:SS` v miestnom čase firmy, príznaky 0 a 1, jazyk `cs_CZ`): ```json title="Webhook doručí (POST na vašu adresu): new_contact" [ { "id": 1207, "guid": null, "emailaddress": "eva.horakova@example.cz", "domain": "example.cz", "name": "Eva", "surname": "Horáková", "titlesbefore": null, "titlesafter": null, "salution": null, "company": null, "street": null, "town": null, "postalcode": null, "country": null, "cellphone": null, "phone": null, "language": "cs_CZ", "birthday": null, "nameday": null, "gender": null, "notes": null, "realname": "Eva Horáková", "blacklisted": 0, "is_blacklisted": false, "hardbounced": 0, "softbounced": 0, "created": "2026-10-01 10:00:00", "updated": "2026-10-01 10:00:00", "created_at": "2026-10-01 10:00:00", "last_updated_at": "2026-10-01 10:00:00", "origin": "manual", "contactlists": [], "customfields": [], "event": "new_contact" } ] ``` ```json title="Webhook doručí (POST na vašu adresu): unsubscribed_contact" [ { "id": 1207, "guid": null, "emailaddress": "eva.horakova@example.cz", "domain": "example.cz", "name": "Eva", "surname": "Horáková", "titlesbefore": null, "titlesafter": null, "salution": null, "company": null, "street": null, "town": null, "postalcode": null, "country": null, "cellphone": null, "phone": null, "language": "cs_CZ", "birthday": null, "nameday": null, "gender": null, "notes": null, "realname": "Eva Horáková", "blacklisted": 0, "is_blacklisted": false, "hardbounced": 0, "softbounced": 0, "created": "2026-10-01 10:00:00", "updated": "2026-10-01 10:00:00", "created_at": "2026-10-01 10:00:00", "last_updated_at": "2026-10-01 10:00:00", "origin": "manual", "contactlists": [], "customfields": [], "event": "unsubscribed_contact", "reason": "admin", "unsubscribed_contactlist_ids": [], "campaign_type": null, "campaign_id": null, "email_statistic_id": null, "trigger_event": null } ] ``` E-mailové udalosti posielajú objekt: ```json title="sent_email, delivery_status, email_open, email_click" { "event": "email_click", "id": 81234, "contact": {"id": 1207, "emailaddress": "eva.horakova@example.cz"}, "campaign_type": "newsletter", "campaign_id": 151, "email_statistic_id": "c151", "trigger_event": null, "sid": 50211, "url": "https://www.example.cz/novinky", "clicked_at": "2026-10-02 09:14:03" } ``` • `sent_email` a `delivery_status` majú miesto `sid`, `url` a `clicked_at` polia `finished_at`, `delivery_status` (`delivered`, `softbounced`, `hardbounced`) a `remote_response` (odpoveď poštového servera pri vrátení); `email_open` má `sid` a `opened_at`. • `campaign_type`: `newsletter`, `automation`, `transactional`, `doi`, `test`. `email_statistic_id`: `c`, alebo `a:` (rovnaké ID ako v [CSV štatistikách](https://www.postarna.sk/docs/api/smartemailing#csv-statistiky)). • `id` e-mailovej udalosti je jedinečné; pri kontaktových udalostiach je `id` ID kontaktu. ### Doručovanie a opakovanie • Poštárna kontroluje nové udalosti každých zhruba 30 sekúnd; jeden webhook dostane v jednom behu najviac 20 položiek, najstaršie prvé, každú samostatne. • Úspech = odpoveď 2xx do 30 sekúnd. Až potom sa posunie na ďalšiu položku. • Čokoľvek iné (iný stav, vypršanie času, odmietnutá adresa) sa počíta ako chyba a rovnaká položka prijde znovu pri ďalšom behu. **Nič sa nepreskočí**, ale tá istá položka môže prísť viackrát (doručenie aspoň raz). • Po **10 chybách v rade** sa webhook sám vypne (`active: 0`); stav, posledný kód a počet chýb ukáže `GET /api/v3/web-hooks`. Znova ho zapnete v aplikácii (Nastavenia › Dátové zdroje › Webhooky, Zapnúť; chyby sa vynulujú) alebo zmazaním a novou registráciou. ### Zabezpečenie Poštárna webhooky **nepodpisuje** (žiadna hlavička s HMAC). Overujte ich takto: • vždy `https://`, • `basic_auth` s dlhým náhodným heslom a kontrolou hlavičky `Authorization` v konštantnom čase, • voliteľne tajná časť cesty (`https://crm.example.sk/postarna/`), • odpovedajte rýchlo (2xx) a spracovanie odložte do radu; spracovanie musí zvládnuť opakované doručenie. Ukázkový príjemca: [recept](https://www.postarna.sk/docs/api/recipe-webhook-consumer). ## Uzol `webhook` v automatizácii ```json title="Uzol webhook" {"id": "crm", "type": "webhook", "config": { "url": "https://crm.example.cz/hooks/postarna?email={{df_emailaddress}}", "method": "POST", "headers": [{"name": "X-Source", "value": "postarna"}], "body": "{\"email\": \"{{df_emailaddress}}\", \"name\": \"{{df_name}}\", \"event\": \"cart\"}", "basicAuth": {"enabled": true, "username": "postarna", "password": ""}}} ``` • Zástupné značky kontaktu fungujú v adrese (hodnoty sa zakódujú do URL), v tele (pri JSON tele sa escapujú pre reťazec JSON) a v hodnotách hlavičiek. POST bez vlastnej hlavičky `Content-Type` posiela `application/json`; GET telo nemá. • Volá sa z radu; neúspech (iná odpoveď než 2xx, chyba siete) sa opakuje 5-krát po 5 minútach, potom sa zaznamená zlyhanie akcie `other`, na ktoré môže reagovať spúšťač `action_failed`. • Heslo `basicAuth` je len na zápis: detail ukazuje `passwordSet: true`; bez nového hesla zostane uložené. Kópia automatizácie heslo nekopíruje. Uloženie hesla potrebuje šifrovací kľúč servera (inak 503 `unavailable` / `data_key`). • Pozastavený scenár, zmazaný uzol alebo zmazaný kontakt zastaví ďalšie pokusy. • Volania (bez adries a osobných údajov) a ich výsledky ukazuje `GET /automations/{id}/report` v `webhooks`. --- # MCP pre AI asistentov Server MCP (Model Context Protocol) dovolí AI asistentovi pracovať v účte Poštárne: hľadať a upravovať kontakty, zakladať zoznamy a segmenty, písať šablóny, pripraviť a poslať kampaň, stavať automatizácie a čítať štatistiky. Asistent pracuje s rovnakými pravidlami ako API. **Adresa servera:** `https://www.postarna.cz/mcp` (rovnaká pre všetky firmy; firmu vyberiete pri povolení prístupu). ## Pripojenie ### ChatGPT 1. Zapnite režim vývojára: Settings › Apps & Connectors › Advanced settings › Developer mode (platené plány; názvy ponúk sa v ChatGPT menia). 2. V Apps & Connectors zvoľte Create, názov Poštárna, adresa servera vyššie, overenie OAuth. 3. ChatGPT vás presmeruje do Poštárne: prihláste sa, vyberte firmu a prístup a povoľte ho. 4. V novom chate zapnite konektor Poštárna a napíšte, čo má urobiť. ### Claude 1. Settings › Connectors › Add custom connector (vo firemných plánoch pridáva konektor vlastník organizácie). 2. Názov Poštárna, adresa servera vyššie; OAuth Client ID a Secret nechajte prázdne, Claude sa zaregistruje sám. 3. Connect, prihlásenie do Poštárne, výber firmy a prístupu, povolenie. ### Ďalší klienti • Klienti s OAuth (Claude Code, Cursor, VS Code ...) potrebujú len adresu: napríklad `claude mcp add --transport http postarna https://www.postarna.cz/mcp`. • Klient, ktorý vie len hlavičku: API kľúč v `Authorization: Bearer pst_...` (kľúč s prístupom `read` alebo `full`). ## Prístup a rozsahy • **Plný prístup** (`full`): všetko, čo dovolí rola člena, ktorý prístup povolil. • **Len na čítanie** (`read`): len operácie s úrovňou `read`; zápis vráti 403 `forbidden` / `scope`. Takéto pripojenie nič nezmení ani neodošle. • Členov, pozvánky, API kľúče a pripojené aplikácie asistent nikdy nespravuje. • Odpojenie: Nastavenia › Dátové zdroje › AI asistenti › Pripojené aplikácie › Odpojiť (alebo odobratie konektora v klientovi). Pripojenie skončí aj odchodom člena z firmy. ## Nástroje Každý nástroj zodpovedá jednej trase API v1 (argumenty pod názvami z API, výsledok JSON). Zoznamy vracajú `{items, total, page, pageSize, hasMore, nextPage}`. • Účet: `get_account`, `list_shops`, `get_dashboard`, `search`, `list_notifications`. • Kontakty: `search_contacts`, `get_contact`, `create_contact`, `update_contact`, `unsubscribe_contact`, `delete_contact`, `erase_contact`, `blacklist_contact`, `list_suppressions` a ďalšie. • Zoznamy, vlastné polia, účely, segmenty, šablóny, kampane, automatizácie, formuláre, importy, štatistiky, kupóny a nastavenia e-shopu. • Všeobecné: `list_api_endpoints` (všetky trasy, ktoré token smie volať), `call_api` (ktorákoľvek z nich) a `get_api_reference` (kontrakt API). V [skupine referencií](https://www.postarna.sk/docs/api/reference) má každá operácia, ktorú nástroj obaľuje, v OpenAPI pole `x-mcp-tool` s názvom nástroja. ## Potvrdenie pred nevratnou akciou Operácie, ktoré posielajú skutočným ľuďom alebo mažú dáta (v OpenAPI `x-mcp-confirm`), nástroj nevykoná hneď: 1. Prvé volanie vráti **náhľad** `{preview: true, confirmRequired: true, action, effect, details, confirm, expiresAt}`: komu, koľko, čo sa stane. 2. Asistent náhľad ukáže človeku a až po jeho súhlase zavolá rovnaký nástroj s rovnakými argumentmi a `confirm` = token z náhľadu. 3. Token platí 15 minút a len pre presne to volanie a stav, ktorý náhľad ukázal. Keď sa kampaň, automatizácia alebo počty medzitým zmenia, prijde nový náhľad. Týka sa to schválenia a obnovenia kampane, zapnutia automatizácie, ručného pridania kontaktov a uvoľnenia čakajúcich, každého mazania, odhlásenia a výmazu kontaktu, kontaktu so súhlasom, odvolania súhlasu, odobratia zo zoznamu a importu. Rovnaký krok majú zmeny, ktoré spustia zapnutú automatizáciu (pridanie do zoznamu, objednávka, úprava šablóny, ktorú automatizácia posiela, udalosť kontaktu, zmena sledovaného poľa, uloženie bežiaceho grafu). Odosielacie trasy sa dajú volať len ich vlastným nástrojom, `call_api` ich odmietne. ## Protokol (pre vývojárov klientov) • Streamable HTTP, verzia 2025-11-25 (prijme aj 2025-06-18 a 2025-03-26), jeden koncový bod `POST /mcp`, JSON-RPC 2.0, dávka najviac 20 správ. Server je bezstavový (`GET` a `DELETE /mcp` vracia 405). • Bez platného tokenu 401 s `WWW-Authenticate: Bearer resource_metadata="https://www.postarna.cz/.well-known/oauth-protected-resource/mcp"`. • OAuth 2.1: dynamická registrácia `POST /oauth/register`, autorizácia s PKCE S256 `GET /oauth/authorize`, tokeny `POST /oauth/token` (prístupový `pso_...` 1 hodinu, obnovovací `psr_...` 30 dní s rotáciou), odvolanie `POST /oauth/revoke`. Metadáta: `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`. • Limit 300 správ JSON-RPC za minútu na token (429 s `Retry-After: 60`). • Každé volanie nástroja sa zapíše do historie účtu s názvom aplikácie (bez argumentov a osobných údajov). --- # Kompatibilita so SmartEmailingom Integrácia napísaná pre REST API v3 SmartEmailingu funguje s Poštárnou po zmene adresy, užívateľského mena a kľúča: rovnaké cesty, obálky, chyby, stránkovanie a formáty. ## Prihlásenie • Adresa: `https://www.postarna.cz/api/v3/` (namiesto `https://app.smartemailing.cz/api/v3/`). • HTTP Basic: užívateľské meno je **e-mail aktívneho člena firmy**, heslo je **API kľúč Poštárne** (`pst_...`). Funguje aj `Authorization: Bearer pst_...`. • Platí rola a prístup kľúča aj limity požiadaviek firmy (hlavičky `X-RateLimit-*`, 429). ```bash title="Požiadavka: GET /api/v3/account-info" curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \ -u "$POSTARNA_USER:$POSTARNA_API_KEY" ``` ```json title="Odpoveď: 200 OK" { "status": "ok", "meta": [], "data": { "account_id": 4, "guid": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f", "username": "admin@example.cz", "firstname": null, "surname": null, "company": "Example s.r.o.", "phone": null } } ``` ## Operácie | Metóda a cesta | Čo robí | |---|---| | `GET /ping` | test spojenia (bez prihlásenia) | | `GET`, `POST /check-credentials` | overenie prihlásenia | | `GET /account-info` | účet; `guid` je ID firmy pre API v1 | | `GET /contacts` | kontakty: filtre `emailaddress`, `id`, `blacklisted`, `hardbounced`; `expand=customfields` | | `GET /contacts/{id}` | jeden kontakt | | `GET /contactlists`, `GET /contactlists/{id}` | zoznamy | | `GET /customfields` | vlastné polia; `expand=customfield_options` | | `GET`, `POST /web-hooks`, `DELETE /web-hooks/{id}` | [účtové webhooky](https://www.postarna.sk/docs/api/webhooks) | • Obálka: `{"status": "ok" | "created" | "error", "meta": [] | {...}, "data": ...}`. • Stránkovanie `limit` (východiskovo a najviac 500) a `offset`, `meta` `{total_count, displayed_count, offset, limit}`; `select=a,b` vyberie vlastnosti, `sort=a,-b` triedi. • Formáty ako SmartEmailing: časy `YYYY-MM-DD HH:MM:SS` v miestnom čase firmy, príznaky 0 a 1, pohlavie `M` / `F`, jazyk `cs_CZ`, `sk_SK`. • Chyby: 401 `Authentication Failed`, 403, 404 `Not Found`, 405 `Method not allowed`, 409 `Already exists`, 422 `Validation failed: `, 429 `Rate limit exceeded (...)`, vždy ako `{"status": "error", "meta": [], "message": "..."}`. ## Čo zatiaľ chýba **Zápis cez API v3 neexistuje**: import kontaktov, úpravy zoznamov a odosielanie e-mailov cez v3 vráti 405 (nikdy tichý úspech). Na zápis použite API v1 ([kontakty](https://www.postarna.sk/docs/api/contacts-and-consent), [import](https://www.postarna.sk/docs/api/recipe-import-contacts), [kampane](https://www.postarna.sk/docs/api/campaigns)). ## CSV štatistiky {#csv-statistiky} Na `https://www.postarna.cz/api/csv/` s rovnakým prihlásením (len v hlavičke, nie v adrese), CSV s bodkočiarkou: • `GET /statistics/email/automation-email-statistic-id[/{automation_id}]`: e-mailové uzly automatizácií a ich ID štatistiky. • `GET /statistics/email/{sent|opened|clicked|bounced|unsubscribed}-detail/{email_statistic_id}` s `interval_from` a `interval_to` (`YYYY-MM-DD HH:MM:SS`, miestny čas): jeden riadok na kontakt a udalosť. ID štatistiky: `c`, alebo `a:`. Strojové otvorenia a kliky sa nepočítajú. • `GET /list-contacts?listid=`: členovia zoznamu vo všetkých stavoch. Ostatné metódy CSV API SmartEmailingu vracajú 404. --- # Prehľad operácií Podrobná technická referencia každej skupiny (parametre, telá, odpovede, chyby a schémy) je po anglicky, rovnako ako dokument [OpenAPI 3.1](https://www.postarna.cz/api/openapi.json), z ktorého sa generuje. Len jednu skupinu načítate parametrom `?tag=` (napríklad `https://www.postarna.cz/api/openapi.json?tag=Automations`). Každá operácia v OpenAPI nesie: • `x-postarna-permission`: modul, úroveň a potrebný prístup kľúča, • `x-mcp-tool`: nástroj servera MCP, ktorý ju obaľuje, • `x-mcp-confirm`: operácia posiela skutočným ľuďom alebo maže (cez MCP len s potvrdením), • pri odpovediach zoznam kódov chýb a hodnôt `message`, ktoré trasa môže vrátiť. Cesty sa počítajú od `https://www.postarna.cz`; `{tenant}` je ID firmy. ### Contacts | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/contacts` | [List contacts (search, filters, paging)](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-list) | | POST | `/api/v1/tenants/{tenant}/contacts` | [Create a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-create) | | POST | `/api/v1/tenants/{tenant}/contacts/bulk` | [Start a bulk action over contacts in the background](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-bulk-start) | | GET | `/api/v1/tenants/{tenant}/contacts/duplicates` | [Find possible duplicate contacts](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-duplicates) | | GET | `/api/v1/tenants/{tenant}/contacts/summary` | [Count contacts by status](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-summary) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Get a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-detail) | | PATCH | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Update a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-update) | | DELETE | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Delete a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-delete) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/activities` | [List activities of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-activities) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/activities` | [Add a manual activity (note) to a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-activity-add) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/automation-runs` | [The real journey of a contact through the automations (runs and steps)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-automation-runs) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist` | [Blacklist a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-blacklist) | | DELETE | `/api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist` | [Remove a contact from the blacklist](https://www.postarna.sk/docs/api/reference-contacts#op-contact-unblacklist) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/coupons` | [List coupons given to a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-coupons) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/erase` | [Erase a contact (GDPR, irreversible)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-erase) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/export` | [Export all data of a contact (GDPR access)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-export) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/neighbors` | [Previous and next contact of a filtered list](https://www.postarna.sk/docs/api/reference-contacts#op-contact-neighbors) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes` | [List consents (purposes) of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purposes) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes` | [Record a consent (purpose) of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purpose-assign) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes/{consent_id}/withdraw` | [Withdraw a consent of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purpose-withdraw) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/segments` | [List segments a contact belongs to](https://www.postarna.sk/docs/api/reference-contacts#op-contact-segments) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/unsubscribe` | [Unsubscribe a contact from everything](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-unsubscribe) | | GET | `/api/v1/tenants/{tenant}/custom-fields` | [List custom fields](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-index) | | POST | `/api/v1/tenants/{tenant}/custom-fields` | [Create a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-create) | | PATCH | `/api/v1/tenants/{tenant}/custom-fields/{field_id}` | [Update a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-update) | | DELETE | `/api/v1/tenants/{tenant}/custom-fields/{field_id}` | [Delete a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-delete) | | GET | `/api/v1/tenants/{tenant}/purposes` | [List purposes of processing (consent types)](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-index) | | POST | `/api/v1/tenants/{tenant}/purposes` | [Create a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-create) | | PATCH | `/api/v1/tenants/{tenant}/purposes/{purpose_id}` | [Update a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-update) | | DELETE | `/api/v1/tenants/{tenant}/purposes/{purpose_id}` | [Delete a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-delete) | | POST | `/api/v1/tenants/{tenant}/purposes/{purpose_id}/to-contact-list` | [Create a list of the contacts with a purpose](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-to-list) | | GET | `/api/v1/tenants/{tenant}/search` | [Search contacts, campaigns, templates and more](https://www.postarna.sk/docs/api/reference-contacts#op-search) | | GET | `/api/v1/tenants/{tenant}/suppressions` | [List suppressed addresses](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-list) | | POST | `/api/v1/tenants/{tenant}/suppressions` | [Suppress an address](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-add) | | POST | `/api/v1/tenants/{tenant}/suppressions/blacklist-import` | [Import addresses to the blacklist](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-blacklist-import) | | DELETE | `/api/v1/tenants/{tenant}/suppressions/{email}` | [Remove one suppression](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-remove) | ### Lists | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/lists` | [List contact lists](https://www.postarna.sk/docs/api/reference-lists#op-lists-index) | | POST | `/api/v1/tenants/{tenant}/lists` | [Create a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-create) | | POST | `/api/v1/tenants/{tenant}/lists/merge` | [Merge lists into a new list (background)](https://www.postarna.sk/docs/api/reference-lists#op-lists-merge) | | POST | `/api/v1/tenants/{tenant}/lists/tags` | [Change labels of lists](https://www.postarna.sk/docs/api/reference-lists#op-lists-tags) | | GET | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Get a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-show) | | PATCH | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Update a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-update) | | DELETE | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Delete a list (only the list, with its contacts, or keeping contacts in other lists)](https://www.postarna.sk/docs/api/reference-lists#op-lists-delete) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/autofill` | [Fill empty name day, gender and salutations of the members](https://www.postarna.sk/docs/api/reference-lists#op-lists-autofill) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/copy` | [Copy a list with its members](https://www.postarna.sk/docs/api/reference-lists#op-lists-copy) | | GET | `/api/v1/tenants/{tenant}/lists/{list_id}/members` | [List members of a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members` | [Add contacts to a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-add-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members/remove` | [Remove contacts from a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-remove-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members/unsubscribe` | [Unsubscribe contacts from a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-unsubscribe-members) | ### Segments | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/segments` | [List segments](https://www.postarna.sk/docs/api/reference-segments#op-segments-index) | | POST | `/api/v1/tenants/{tenant}/segments` | [Create a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-create) | | POST | `/api/v1/tenants/{tenant}/segments/preview` | [Count the contacts of a segment definition (no save)](https://www.postarna.sk/docs/api/reference-segments#op-segments-preview) | | POST | `/api/v1/tenants/{tenant}/segments/tags` | [Change labels of segments](https://www.postarna.sk/docs/api/reference-segments#op-segments-tags) | | GET | `/api/v1/tenants/{tenant}/segments/{segment}` | [Get a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-show) | | PATCH | `/api/v1/tenants/{tenant}/segments/{segment}` | [Update a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-update) | | DELETE | `/api/v1/tenants/{tenant}/segments/{segment}` | [Delete a segment no campaign, segment or automation names](https://www.postarna.sk/docs/api/reference-segments#op-segments-delete) | | GET | `/api/v1/tenants/{tenant}/segments/{segment}/members` | [List the members of a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-members) | | POST | `/api/v1/tenants/{tenant}/segments/{segment}/recompute` | [Recompute a segment now](https://www.postarna.sk/docs/api/reference-segments#op-segments-recompute) | | POST | `/api/v1/tenants/{tenant}/segments/{segment}/to-list` | [Convert a segment into a manual list of its mailable contacts](https://www.postarna.sk/docs/api/reference-segments#op-segments-to-list) | ### Campaigns | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/campaigns` | [List campaigns](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-index) | | POST | `/api/v1/tenants/{tenant}/campaigns` | [Create a campaign (draft)](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-create) | | POST | `/api/v1/tenants/{tenant}/campaigns/audience` | [Count and explain the recipients of an audience](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-audience) | | POST | `/api/v1/tenants/{tenant}/campaigns/tags` | [Change labels of campaigns](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-tags) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Get a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-show) | | PATCH | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Update a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-update) | | DELETE | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Delete a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-delete) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/approve` | [Approve a campaign: send now or schedule](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-approve) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/cancel` | [Cancel a scheduled or paused campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-cancel) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/content` | [Get the content of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-content) | | PUT | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/content` | [Save the content of a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-save-content) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/pause` | [Pause a sending or scheduled campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-pause) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/preview` | [Render a campaign for one contact](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-preview) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/resume` | [Resume a paused campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-resume) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/stats` | [Statistics of a campaign by provider and domain](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-stats) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/test` | [Send a test e-mail of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-test) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Get the language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-index) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Create language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-create) | | PUT | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Change the language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-arrange) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/approve` | [Approve the language variants (send or schedule)](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-approve) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/cancel` | [Cancel the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-cancel) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/pause` | [Pause the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-pause) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/preview` | [Preview the audience split of language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-preview) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/resume` | [Resume the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-resume) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/stats` | [Statistics of the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-stats) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/versions` | [List saved content versions of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-versions) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/versions/{version_id}` | [Get one content version of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-version) | | GET | `/api/v1/tenants/{tenant}/senders` | [List verified senders](https://www.postarna.sk/docs/api/reference-campaigns#op-senders-index) | ### Templates and content | Metóda | Cesta | Popis | |---|---|---| | POST | `/api/v1/tenants/{tenant}/content/lint` | [Check e-mail content (merge tags, links, required parts)](https://www.postarna.sk/docs/api/reference-templates#op-content-lint) | | POST | `/api/v1/tenants/{tenant}/content/spam-check` | [Antispam check of e-mail content](https://www.postarna.sk/docs/api/reference-templates#op-content-spam-check) | | GET | `/api/v1/tenants/{tenant}/editor-elements` | [List saved editor elements](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-index) | | POST | `/api/v1/tenants/{tenant}/editor-elements` | [Save an editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-create) | | PATCH | `/api/v1/tenants/{tenant}/editor-elements/{element_id}` | [Update a saved editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-update) | | DELETE | `/api/v1/tenants/{tenant}/editor-elements/{element_id}` | [Delete a saved editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-delete) | | GET | `/api/v1/tenants/{tenant}/file-folders` | [List folders of the file manager](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-index) | | POST | `/api/v1/tenants/{tenant}/file-folders` | [Create a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-create) | | PATCH | `/api/v1/tenants/{tenant}/file-folders/{folder_id}` | [Rename a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-update) | | DELETE | `/api/v1/tenants/{tenant}/file-folders/{folder_id}` | [Delete a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-delete) | | GET | `/api/v1/tenants/{tenant}/files` | [List files of the file manager](https://www.postarna.sk/docs/api/reference-templates#op-files-index) | | POST | `/api/v1/tenants/{tenant}/files` | [Upload a file (multipart)](https://www.postarna.sk/docs/api/reference-templates#op-files-upload) | | POST | `/api/v1/tenants/{tenant}/files/stock-photo` | [Save a stock photo to the file manager](https://www.postarna.sk/docs/api/reference-templates#op-files-stock-photo) | | POST | `/api/v1/tenants/{tenant}/files/video-thumbnail` | [Create a video thumbnail image](https://www.postarna.sk/docs/api/reference-templates#op-files-video-thumbnail) | | GET | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Get a file](https://www.postarna.sk/docs/api/reference-templates#op-files-show) | | PATCH | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Rename or move a file](https://www.postarna.sk/docs/api/reference-templates#op-files-update) | | DELETE | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Delete a file](https://www.postarna.sk/docs/api/reference-templates#op-files-delete) | | POST | `/api/v1/tenants/{tenant}/files/{asset_id}/picked` | [Record that a file was used](https://www.postarna.sk/docs/api/reference-templates#op-files-picked) | | GET | `/api/v1/tenants/{tenant}/footers` | [List footers](https://www.postarna.sk/docs/api/reference-templates#op-footers-index) | | POST | `/api/v1/tenants/{tenant}/footers` | [Create a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-create) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Get a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-show) | | PATCH | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Rename a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-rename) | | DELETE | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Delete a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-delete) | | PUT | `/api/v1/tenants/{tenant}/footers/{footer_id}/content` | [Save the content of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-content) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/copy` | [Copy a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-copy) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/default` | [Make a footer the default](https://www.postarna.sk/docs/api/reference-templates#op-footers-default) | | DELETE | `/api/v1/tenants/{tenant}/footers/{footer_id}/default` | [Stop using a footer as the default](https://www.postarna.sk/docs/api/reference-templates#op-footers-default-off) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/publish` | [Publish a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-publish) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}/versions` | [List saved versions of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-versions) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}/versions/{version_id}` | [Get one version of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-version) | | GET | `/api/v1/tenants/{tenant}/landing-pages` | [List landing pages](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-index) | | POST | `/api/v1/tenants/{tenant}/landing-pages` | [Create a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-create) | | GET | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Get a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-show) | | PATCH | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Update a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-update) | | DELETE | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Delete a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-delete) | | POST | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}/copy` | [Copy a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-copy) | | GET | `/api/v1/tenants/{tenant}/script-templates` | [List script templates (Twig)](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-index) | | POST | `/api/v1/tenants/{tenant}/script-templates` | [Create a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-create) | | GET | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Get a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Update a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Delete a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-delete) | | GET | `/api/v1/tenants/{tenant}/sms-templates` | [List SMS templates](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-index) | | POST | `/api/v1/tenants/{tenant}/sms-templates` | [Create an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-create) | | GET | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Get an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Update an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Delete an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-delete) | | POST | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}/copy` | [Copy an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-copy) | | GET | `/api/v1/tenants/{tenant}/stock-photos` | [Search stock photos](https://www.postarna.sk/docs/api/reference-templates#op-stock-photos-search) | | GET | `/api/v1/tenants/{tenant}/stock-photos/status` | [Whether the stock photo search is available](https://www.postarna.sk/docs/api/reference-templates#op-stock-photos-status) | | GET | `/api/v1/tenants/{tenant}/surveys` | [List surveys](https://www.postarna.sk/docs/api/reference-templates#op-surveys-index) | | POST | `/api/v1/tenants/{tenant}/surveys` | [Create a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-create) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Get a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-show) | | PATCH | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Update a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-update) | | DELETE | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Delete a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-delete) | | POST | `/api/v1/tenants/{tenant}/surveys/{survey_id}/copy` | [Copy a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-copy) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}/responses` | [List responses of a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-responses) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}/results` | [Summary results of a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-results) | | GET | `/api/v1/tenants/{tenant}/templates` | [List templates](https://www.postarna.sk/docs/api/reference-templates#op-templates-index) | | POST | `/api/v1/tenants/{tenant}/templates` | [Create a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-create) | | POST | `/api/v1/tenants/{tenant}/templates/tags` | [Change labels of templates](https://www.postarna.sk/docs/api/reference-templates#op-templates-tags) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Get a template with its content](https://www.postarna.sk/docs/api/reference-templates#op-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Update template settings (name, subject, preheader ...)](https://www.postarna.sk/docs/api/reference-templates#op-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Delete a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-delete) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/archive` | [Archive a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-archive) | | PUT | `/api/v1/tenants/{tenant}/templates/{template_id}/content` | [Save the content of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-save-content) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/convert-to-visual` | [Convert an HTML template to the visual editor](https://www.postarna.sk/docs/api/reference-templates#op-templates-convert-to-visual) | | DELETE | `/api/v1/tenants/{tenant}/templates/{template_id}/draft` | [Discard the unpublished draft of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-discard-draft) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/duplicate` | [Duplicate a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-duplicate) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/publish` | [Publish the draft of a template used by an active automation](https://www.postarna.sk/docs/api/reference-templates#op-templates-publish) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/test` | [Send a test e-mail of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-test) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/unarchive` | [Restore an archived template](https://www.postarna.sk/docs/api/reference-templates#op-templates-unarchive) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}/versions` | [List saved content versions of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-versions) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}/versions/{version_id}` | [Get one content version of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-version) | | GET | `/api/v1/tenants/{tenant}/test-recipients` | [List the test addresses of the company](https://www.postarna.sk/docs/api/reference-templates#op-test-recipients) | | PUT | `/api/v1/tenants/{tenant}/test-recipients` | [Replace the test addresses of the company](https://www.postarna.sk/docs/api/reference-templates#op-test-recipients-update) | | GET | `/api/v1/tenants/{tenant}/unsubscribe-pages` | [List unsubscribe pages](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-index) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages` | [Create an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-create) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/preview` | [Render an unsubscribe page preview](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-preview) | | GET | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Get an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-show) | | PATCH | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Update an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-update) | | DELETE | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Delete an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-delete) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/copy` | [Copy an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-copy) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/default` | [Make an unsubscribe page the default](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-default) | | DELETE | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/default` | [Stop using an unsubscribe page as the default](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-default-off) | ### Automations | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/automations` | [List automations](https://www.postarna.sk/docs/api/reference-automations#op-automations-index) | | POST | `/api/v1/tenants/{tenant}/automations` | [Create an automation (draft)](https://www.postarna.sk/docs/api/reference-automations#op-automations-create) | | POST | `/api/v1/tenants/{tenant}/automations/resolve-time` | [Resolve a time spec to a moment (preview)](https://www.postarna.sk/docs/api/reference-automations#op-automations-resolve-time) | | POST | `/api/v1/tenants/{tenant}/automations/tags` | [Change labels of automations](https://www.postarna.sk/docs/api/reference-automations#op-automations-tags) | | POST | `/api/v1/tenants/{tenant}/automations/validate` | [Validate a graph without saving](https://www.postarna.sk/docs/api/reference-automations#op-automations-validate) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Get an automation with its graph and issues](https://www.postarna.sk/docs/api/reference-automations#op-automations-show) | | PATCH | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Update name, description or labels of an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-update) | | DELETE | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Delete an automation that never ran](https://www.postarna.sk/docs/api/reference-automations#op-automations-delete) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/activate` | [Activate (start) an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-activate) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/contacts` | [Add contacts by hand to a running automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-add-contacts) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/copy` | [Copy an automation as a new draft](https://www.postarna.sk/docs/api/reference-automations#op-automations-copy) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/counts` | [Live counts per node and output](https://www.postarna.sk/docs/api/reference-automations#op-automations-counts) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/editing` | [Report that the editor has a scenario open and see who else has it](https://www.postarna.sk/docs/api/reference-automations#op-automations-editing) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/editor` | [Everything the editor needs in one answer](https://www.postarna.sk/docs/api/reference-automations#op-automations-editor) | | PUT | `/api/v1/tenants/{tenant}/automations/{automation_id}/graph` | [Save the graph of an automation (new version)](https://www.postarna.sk/docs/api/reference-automations#op-automations-save-graph) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/passes` | [Contacts that went through a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-node-passes) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/release` | [Release the contacts waiting in a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-release) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/reschedule` | [Recompute the end of waiting in a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-reschedule) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/pause` | [Pause an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-pause) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/report` | [Statistics of the e-mail nodes (JSON or CSV)](https://www.postarna.sk/docs/api/reference-automations#op-automations-report) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/runs` | [Run history per contact](https://www.postarna.sk/docs/api/reference-automations#op-automations-runs) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/test` | [Test the scenario on today's data (nothing is sent)](https://www.postarna.sk/docs/api/reference-automations#op-automations-test) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/trace` | [Trace one contact through the scenario (nothing is sent)](https://www.postarna.sk/docs/api/reference-automations#op-automations-trace) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/versions` | [List saved versions of the graph](https://www.postarna.sk/docs/api/reference-automations#op-automations-versions) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/versions/{version}` | [Get one saved version of the graph](https://www.postarna.sk/docs/api/reference-automations#op-automations-version) | | POST | `/api/v1/tenants/{tenant}/contact-events` | [Record an event of a contact (custom event, cart, page visit)](https://www.postarna.sk/docs/api/reference-automations#op-contact-events-create) | ### Forms | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/forms` | [List forms](https://www.postarna.sk/docs/api/reference-forms#op-forms-list) | | POST | `/api/v1/tenants/{tenant}/forms` | [Create a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-create) | | GET | `/api/v1/tenants/{tenant}/forms/doi-templates` | [List templates usable as the double opt-in e-mail](https://www.postarna.sk/docs/api/reference-forms#op-forms-doi-templates) | | POST | `/api/v1/tenants/{tenant}/forms/preview` | [Render a form preview](https://www.postarna.sk/docs/api/reference-forms#op-forms-preview) | | POST | `/api/v1/tenants/{tenant}/forms/tags` | [Change labels of forms](https://www.postarna.sk/docs/api/reference-forms#op-forms-tags) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Get a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-show) | | PATCH | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Update a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-update) | | DELETE | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Delete a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-delete) | | POST | `/api/v1/tenants/{tenant}/forms/{form_id}/copy` | [Copy a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-copy) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/embed` | [Get the embed code of a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-embed) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/history` | [Change history of a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-history) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/welcome` | [Get the e-mail after a sign-up (the form's own automation)](https://www.postarna.sk/docs/api/reference-forms#op-forms-welcome) | | PUT | `/api/v1/tenants/{tenant}/forms/{form_id}/welcome` | [Switch the e-mail after a sign-up on or off](https://www.postarna.sk/docs/api/reference-forms#op-forms-welcome-save) | ### Imports and exports | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/export-fields` | [Fields an export can contain](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-export-fields) | | GET | `/api/v1/tenants/{tenant}/exports` | [List exports](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-index) | | POST | `/api/v1/tenants/{tenant}/exports` | [Start a CSV export](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-create) | | GET | `/api/v1/tenants/{tenant}/exports/{export_id}` | [Get an export](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-show) | | GET | `/api/v1/tenants/{tenant}/exports/{export_id}/download` | [Download an export (CSV)](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-download) | | GET | `/api/v1/tenants/{tenant}/imports` | [List imports](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-index) | | POST | `/api/v1/tenants/{tenant}/imports` | [Start an import](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-run) | | POST | `/api/v1/tenants/{tenant}/imports/drafts` | [Start an import draft (wizard)](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-create) | | GET | `/api/v1/tenants/{tenant}/imports/drafts/{import_id}` | [Get an import draft](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-show) | | PUT | `/api/v1/tenants/{tenant}/imports/drafts/{import_id}` | [Save an import draft](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-update) | | POST | `/api/v1/tenants/{tenant}/imports/files` | [Upload a CSV file for import](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-upload) | | POST | `/api/v1/tenants/{tenant}/imports/preview` | [Preview an import: mapping, counts, problems](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-preview) | | GET | `/api/v1/tenants/{tenant}/imports/{import_id}` | [Get an import with its progress and result](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-show) | | DELETE | `/api/v1/tenants/{tenant}/imports/{import_id}` | [Delete an import record](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-delete) | ### Orders, feeds and coupons | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/coupon-stacks` | [List coupon stacks](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-list) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks` | [Create a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-create) | | GET | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}` | [Get a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-show) | | DELETE | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}` | [Delete a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-delete) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/assign` | [Give a coupon of a stack to a contact](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-assign) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/codes` | [Add coupon codes to a stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-import) | | GET | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/coupons` | [List coupons of a stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-assigned) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/used` | [Mark coupons as used](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-used) | | GET | `/api/v1/tenants/{tenant}/feed-articles` | [Search articles of the article feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feed-articles-search) | | GET | `/api/v1/tenants/{tenant}/feed-products` | [Search products of the product feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feed-products-search) | | GET | `/api/v1/tenants/{tenant}/feeds` | [List feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-list) | | POST | `/api/v1/tenants/{tenant}/feeds` | [Create a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-create) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Get a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-show) | | PATCH | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Update a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-update) | | DELETE | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Delete a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-delete) | | POST | `/api/v1/tenants/{tenant}/feeds/{feed_id}/import` | [Import a feed file by upload](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-import) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}/items` | [List items of a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-items) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}/preview` | [Preview a feed (first items, detected fields)](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-preview) | | POST | `/api/v1/tenants/{tenant}/feeds/{feed_id}/refresh` | [Download and process a feed now](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-refresh) | | GET | `/api/v1/tenants/{tenant}/order-states` | [Get the order state mapping](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-order-states-show) | | PUT | `/api/v1/tenants/{tenant}/order-states` | [Replace the order state mapping](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-order-states-replace) | | GET | `/api/v1/tenants/{tenant}/orders` | [List orders](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-list) | | POST | `/api/v1/tenants/{tenant}/orders` | [Create or update an order](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-save) | | POST | `/api/v1/tenants/{tenant}/orders/paid-at` | [Maintenance: fill empty dates of payment of orders (SmartEmailing data)](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-maintenance-orders-paid-at) | | GET | `/api/v1/tenants/{tenant}/orders/{order_id}` | [Get an order](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-show) | ### Statistics | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/conversions` | [Conversions summary](https://www.postarna.sk/docs/api/reference-statistics#op-conversions-summary) | | GET | `/api/v1/tenants/{tenant}/dashboard` | [Dashboard numbers](https://www.postarna.sk/docs/api/reference-statistics#op-dashboard) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}` | [Statistics of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/activity` | [Activity of an automation over time](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-activity) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/conversions` | [Conversions (orders) of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-conversions) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/heatmap` | [Click map of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-heatmap) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/recipients` | [Recipients of an automation with their events (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-recipients) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/report` | [Report of an automation (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-report) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}` | [Statistics of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/activity` | [Activity of a campaign over time](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-activity) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/conversions` | [Conversions (orders) of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-conversions) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/heatmap` | [Click map of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-heatmap) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/recipients` | [Recipients of a campaign with their events (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-recipients) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/report` | [Report of a campaign (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-report) | | GET | `/api/v1/tenants/{tenant}/stats/emails` | [E-mail statistics of campaigns and automations](https://www.postarna.sk/docs/api/reference-statistics#op-stats-emails) | ### Sending and deliverability | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/deliverability/dmarc` | [DMARC summary](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-dmarc) | | GET | `/api/v1/tenants/{tenant}/deliverability/dmarc/report` | [DMARC report detail](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-dmarc-report) | | GET | `/api/v1/tenants/{tenant}/deliverability/domains` | [List domains with their DNS state](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domains) | | POST | `/api/v1/tenants/{tenant}/deliverability/domains` | [Add a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-create) | | PATCH | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}` | [Update a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-update) | | DELETE | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}` | [Delete a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-delete) | | POST | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}/check` | [Check the DNS records of a domain now](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-check) | | GET | `/api/v1/tenants/{tenant}/deliverability/senders` | [Senders with their authentication state](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-senders) | | GET | `/api/v1/tenants/{tenant}/sending-defaults` | [Get the default settings of new campaigns (tracking parameters on or off)](https://www.postarna.sk/docs/api/reference-sending#op-sending-defaults) | | PUT | `/api/v1/tenants/{tenant}/sending-defaults` | [Set whether new campaigns start with tracking parameters](https://www.postarna.sk/docs/api/reference-sending#op-sending-defaults-update) | | GET | `/api/v1/tenants/{tenant}/sending-mode` | [Sending mode of the company (switch, limits)](https://www.postarna.sk/docs/api/reference-sending#op-sending-mode) | | POST | `/api/v1/tenants/{tenant}/sending/domains` | [Add a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-add) | | DELETE | `/api/v1/tenants/{tenant}/sending/domains/{domain_id}` | [Delete a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-delete) | | POST | `/api/v1/tenants/{tenant}/sending/domains/{domain_id}/check` | [Check a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-check) | | POST | `/api/v1/tenants/{tenant}/sending/senders` | [Add a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-add) | | PATCH | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}` | [Update a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-update) | | DELETE | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}` | [Delete a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-delete) | | POST | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/check` | [Check whether a sender address is confirmed](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-check) | | POST | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/resend` | [Send the confirmation e-mail of a sender address again](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-resend) | | GET | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/usage` | [Where a sender is used](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-usage) | | GET | `/api/v1/tenants/{tenant}/sending/setup` | [State of the sending setup (domains and senders)](https://www.postarna.sk/docs/api/reference-sending#op-sending-setup) | ### Account and settings | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/public/price-list` | [Public price list (no authentication)](https://www.postarna.sk/docs/api/reference-account#op-price-list) | | GET | `/api/v1/tenants/{tenant}/account-webhooks` | [List account webhooks and their events](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-index) | | POST | `/api/v1/tenants/{tenant}/account-webhooks` | [Create an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-create) | | PATCH | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}` | [Edit, switch off or on an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-update) | | DELETE | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}` | [Delete an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-delete) | | POST | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}/test` | [Send a test call of an account webhook now](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-test) | | GET | `/api/v1/tenants/{tenant}/billing` | [Tariff, usage and balance](https://www.postarna.sk/docs/api/reference-account#op-billing-overview) | | GET | `/api/v1/tenants/{tenant}/billing/cancel` | [What cancelling the tariff would mean](https://www.postarna.sk/docs/api/reference-account#op-billing-cancel-check) | | GET | `/api/v1/tenants/{tenant}/billing/invoices` | [List invoices](https://www.postarna.sk/docs/api/reference-account#op-billing-invoices) | | GET | `/api/v1/tenants/{tenant}/billing/invoices/{invoice_id}/pdf` | [Download an invoice (PDF)](https://www.postarna.sk/docs/api/reference-account#op-billing-invoice-pdf) | | GET | `/api/v1/tenants/{tenant}/billing/invoices/{invoice_id}/qr.svg` | [QR payment code of an invoice (SVG)](https://www.postarna.sk/docs/api/reference-account#op-billing-invoice-qr) | | GET | `/api/v1/tenants/{tenant}/billing/payments` | [List payments](https://www.postarna.sk/docs/api/reference-account#op-billing-payments) | | GET | `/api/v1/tenants/{tenant}/billing/profile` | [Get the billing profile](https://www.postarna.sk/docs/api/reference-account#op-billing-profile) | | GET | `/api/v1/tenants/{tenant}/billing/quote` | [Price of a tariff](https://www.postarna.sk/docs/api/reference-account#op-billing-quote) | | GET | `/api/v1/tenants/{tenant}/company` | [Get the company data](https://www.postarna.sk/docs/api/reference-account#op-account-company) | | PATCH | `/api/v1/tenants/{tenant}/company` | [Update the company data](https://www.postarna.sk/docs/api/reference-account#op-account-company-update) | | GET | `/api/v1/tenants/{tenant}/consent-settings` | [Consent settings of every shop](https://www.postarna.sk/docs/api/reference-account#op-consent-settings-index) | | PATCH | `/api/v1/tenants/{tenant}/consent-settings/{shop_id}` | [Update the customer exception of a shop](https://www.postarna.sk/docs/api/reference-account#op-consent-settings-update) | | GET | `/api/v1/tenants/{tenant}/grid-tags` | [Labels used in a grid](https://www.postarna.sk/docs/api/reference-account#op-grid-tags-index) | | GET | `/api/v1/tenants/{tenant}/labels` | [List labels](https://www.postarna.sk/docs/api/reference-account#op-labels-index) | | POST | `/api/v1/tenants/{tenant}/labels` | [Create a label](https://www.postarna.sk/docs/api/reference-account#op-labels-create) | | PATCH | `/api/v1/tenants/{tenant}/labels/{label_id}` | [Update a label](https://www.postarna.sk/docs/api/reference-account#op-labels-update) | | DELETE | `/api/v1/tenants/{tenant}/labels/{label_id}` | [Delete a label](https://www.postarna.sk/docs/api/reference-account#op-labels-delete) | | POST | `/api/v1/tenants/{tenant}/labels/{label_id}/assign` | [Assign a label to objects](https://www.postarna.sk/docs/api/reference-account#op-labels-assign) | | POST | `/api/v1/tenants/{tenant}/maintenance/phone-landline-mobile` | [Maintenance: move landline-stored mobile numbers to mobile (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-phone-landline-mobile) | | POST | `/api/v1/tenants/{tenant}/maintenance/se-backfill-contacts` | [Maintenance: fill empty contact fields from a SmartEmailing backup (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-se-backfill) | | POST | `/api/v1/tenants/{tenant}/maintenance/shop-enrich` | [Maintenance: fill empty contact fields from the e-shop feeds (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-shop-enrich) | | POST | `/api/v1/tenants/{tenant}/maintenance/shop-lists` | [Maintenance: rebuild the e-shop lists (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-shop-lists) | | GET | `/api/v1/tenants/{tenant}/notifications` | [List notifications](https://www.postarna.sk/docs/api/reference-account#op-notifications-list) | | POST | `/api/v1/tenants/{tenant}/notifications/delete` | [Delete notifications](https://www.postarna.sk/docs/api/reference-account#op-notifications-delete) | | POST | `/api/v1/tenants/{tenant}/notifications/read` | [Mark notifications as read](https://www.postarna.sk/docs/api/reference-account#op-notifications-read) | | POST | `/api/v1/tenants/{tenant}/notifications/unread` | [Mark notifications as unread](https://www.postarna.sk/docs/api/reference-account#op-notifications-unread) | | GET | `/api/v1/tenants/{tenant}/onboarding` | [State of the onboarding wizard](https://www.postarna.sk/docs/api/reference-account#op-onboarding-show) | | PATCH | `/api/v1/tenants/{tenant}/onboarding` | [Save the onboarding wizard](https://www.postarna.sk/docs/api/reference-account#op-onboarding-update) | | GET | `/api/v1/tenants/{tenant}/rfm` | [State of the RFM analysis](https://www.postarna.sk/docs/api/reference-account#op-rfm-state) | | POST | `/api/v1/tenants/{tenant}/rfm/enable-request` | [Ask to enable the RFM analysis](https://www.postarna.sk/docs/api/reference-account#op-rfm-enable-request) | | GET | `/api/v1/tenants/{tenant}/running-actions` | [Running background actions (imports, exports ...)](https://www.postarna.sk/docs/api/reference-account#op-running-actions-index) | | GET | `/api/v1/tenants/{tenant}/shop-enrich` | [Whether order feed imports fill empty contact fields](https://www.postarna.sk/docs/api/reference-account#op-shop-enrich-state) | | PUT | `/api/v1/tenants/{tenant}/shop-enrich` | [Turn the ongoing contact data enrichment on or off](https://www.postarna.sk/docs/api/reference-account#op-shop-enrich-switch) | | GET | `/api/v1/tenants/{tenant}/shop-settings` | [Sending company data of every shop](https://www.postarna.sk/docs/api/reference-account#op-shop-settings-index) | | PATCH | `/api/v1/tenants/{tenant}/shop-settings/{shop_id}` | [Update the sending company data of a shop](https://www.postarna.sk/docs/api/reference-account#op-shop-settings-update) | | GET | `/api/v1/tenants/{tenant}/shops` | [List shops (e-shops) of the company](https://www.postarna.sk/docs/api/reference-account#op-shops) | | POST | `/api/v1/tenants/{tenant}/shops` | [Create a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-create) | | GET | `/api/v1/tenants/{tenant}/shops/{shop_id}` | [Get a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-show) | | PATCH | `/api/v1/tenants/{tenant}/shops/{shop_id}` | [Update a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-update) | | GET | `/api/v1/tenants/{tenant}/shops/{shop_id}/brand` | [Get the brand settings of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-brand) | | PUT | `/api/v1/tenants/{tenant}/shops/{shop_id}/brand` | [Replace the brand settings of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-brand-update) | | PUT | `/api/v1/tenants/{tenant}/shops/{shop_id}/contact-language` | [Set the default language of new contacts of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-contact-language) | | POST | `/api/v1/tenants/{tenant}/shops/{shop_id}/disable` | [Switch a shop off](https://www.postarna.sk/docs/api/reference-account#op-shops-disable) | | POST | `/api/v1/tenants/{tenant}/shops/{shop_id}/enable` | [Switch a shop on](https://www.postarna.sk/docs/api/reference-account#op-shops-enable) | | GET | `/api/v1/tenants/{tenant}/site-script` | [Every shop's one script line and connection state](https://www.postarna.sk/docs/api/reference-account#op-site-script-index) | | PATCH | `/api/v1/tenants/{tenant}/site-script/{shop_id}` | [Switch the checkout newsletter box of a shop](https://www.postarna.sk/docs/api/reference-account#op-site-script-update) | | POST | `/api/v1/tenants/{tenant}/site-script/{shop_id}/check` | [Test whether the script is on the shop's homepage](https://www.postarna.sk/docs/api/reference-account#op-site-script-check) | | GET | `/api/v1/tenants/{tenant}/smartemailing` | [State of the SmartEmailing migration](https://www.postarna.sk/docs/api/reference-account#op-smartemailing-state) | | GET | `/api/v1/tenants/{tenant}/smartemailing/migrations/{migration_id}` | [Get one SmartEmailing migration run](https://www.postarna.sk/docs/api/reference-account#op-smartemailing-migration) | | GET | `/api/v1/tenants/{tenant}/web-tracking` | [Web tracking state of every shop](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-index) | | GET | `/api/v1/tenants/{tenant}/web-tracking/events` | [List web tracking events](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-events) | | PATCH | `/api/v1/tenants/{tenant}/web-tracking/{shop_id}` | [Switch web tracking of a shop](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-switch) | ### SmartEmailing compatible API v3 | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v3/account-info` | [Account info (guid = tenant id for API v1)](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-account-info) | | GET | `/api/v3/check-credentials` | [Check the credentials](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-check-credentials) | | POST | `/api/v3/check-credentials` | [Check the credentials](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-check-credentials-post) | | GET | `/api/v3/contactlists` | [List contact lists](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contactlists) | | GET | `/api/v3/contactlists/{list_id}` | [Get a contact list](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contactlist) | | GET | `/api/v3/contacts` | [List contacts](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contacts) | | GET | `/api/v3/contacts/{contact_id}` | [Get a contact](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contact) | | GET | `/api/v3/customfields` | [List custom fields](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-customfields) | | GET | `/api/v3/ping` | [Ping (no authentication)](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-ping) | | GET | `/api/v3/web-hooks` | [List account webhooks](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhooks) | | POST | `/api/v3/web-hooks` | [Register an account webhook](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhook-create-post) | | DELETE | `/api/v3/web-hooks/{webhook_id}` | [Delete an account webhook](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhook-delete-delete) | ### SmartEmailing compatible CSV statistics | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/csv/list-contacts` | [Members of a list (CSV)](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-list-contacts) | | GET | `/api/csv/statistics/email/automation-email-statistic-id` | [E-mail statistic ids of automation e-mail nodes](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-automation-statistic-ids) | | GET | `/api/csv/statistics/email/automation-email-statistic-id/{automation_id}` | [E-mail statistic ids of automation e-mail nodes of one automation](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-automation-statistic-ids-one) | | GET | `/api/csv/statistics/email/{kind}-detail/{sid}` | [Per-contact events of an e-mail statistic id (sent, opened, clicked, bounced, unsubscribed)](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-email-detail) | ### MCP server for AI assistants | Metóda | Cesta | Popis | |---|---|---| | POST | `/mcp` | [MCP JSON-RPC endpoint (Streamable HTTP, stateless)](https://www.postarna.sk/docs/api/reference-mcp#op-mcp) | ### OAuth 2.1 for AI assistants | Metóda | Cesta | Popis | |---|---|---| | GET | `/.well-known/oauth-authorization-server` | [Authorization server metadata (RFC 8414)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-server-metadata) | | GET | `/.well-known/oauth-authorization-server/mcp` | [Authorization server metadata (RFC 8414)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-server-metadata-mcp) | | GET | `/.well-known/oauth-protected-resource` | [Protected resource metadata (RFC 9728)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-protected-resource) | | GET | `/.well-known/oauth-protected-resource/mcp` | [Protected resource metadata (RFC 9728)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-protected-resource-mcp) | | GET | `/oauth/authorize` | [Authorization (browser redirect to the consent page)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-authorize) | | POST | `/oauth/register` | [Dynamic client registration (RFC 7591, at most 20 an hour per address)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-register) | | POST | `/oauth/revoke` | [Revoke a token (RFC 7009)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-revoke) | | POST | `/oauth/token` | [Tokens: authorization_code or refresh_token (access pso_... 1 hour, refresh psr_... 30 days, rotated)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-token) | ### This document | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/openapi.json` | [This OpenAPI document](https://www.postarna.sk/docs/api/reference-meta#op-openapi-document) | --- # Chyby a limity ## Tvar chyby API v1 vracia pri chybe vhodný HTTP stav a telo: ```json title="Chyba" {"error": {"code": "validation", "message": "definition.0.currency"}} ``` • `code` je stály strojový kód (tabuľka nižšie). Rozhodujte sa podľa neho a podľa HTTP stavu. • `message` upresní pole alebo dôvod (napríklad `email`, `name`, `version`, `status`, `scope`). Nie je to text pre ľudí. • `params` nesie podrobnosti: `issues` (problémy grafu automatizácie), `expected` a `actual` (počet príjemcov), `current` (verzia), `reason`, `retryAfter`. API v3 kompatibilné so SmartEmailingom má vlastný tvar `{"status": "error", "meta": [], "message": "..."}`, pozrite [Kompatibilita so SmartEmailingom](https://www.postarna.sk/docs/api/smartemailing). ## HTTP stavy | Stav | Kedy | |---|---| | 200, 201, 204 | úspech (201 = vytvorené, 204 = bez tela) | | 400 | neplatný vstup (`validation`) | | 401 | chýba alebo neplatí prihlásenie (`unauthorized`) | | 403 | prihlásenie platí, ale nie je dovolené (`forbidden`) | | 404 | objekt neexistuje (alebo patrí inej firme) | | 405 | trasa nemá túto metódu | | 409 | zmena by porušila stav objektu (`conflict`) | | 410 | objekt už nie je k dispozícii (`expired`) | | 413 | telo požiadavky nad 5 MB | | 415 | telo nie je JSON (`validation` / `contentType`) | | 429 | prekročený limit (`rate_limited`), hlavička `Retry-After` | | 502 | zlyhala vonkajšia služba (`upstream`) | | 503 | služba nie je dostupná (`unavailable`) | | 500 | chyba servera (`server`) | ## Kódy chýb ### `conflict` {#error-conflict} **Význam:** 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). **Čo urobiť:** Read the object again, then repeat with current data; for `recipients` count the audience again and send the new `expectedRecipients`. ### `count_mismatch` {#error-count-mismatch} **Význam:** `expectedRecipients` does not match the audience. **Čo urobiť:** Count again with `POST /campaigns/audience` and send the new number. ### `csrf` {#error-csrf} **Význam:** Browser session request without the CSRF header (never with an API key). **Čo urobiť:** Send the API key in `Authorization` instead of cookies. ### `empty_segment` {#error-empty-segment} **Význam:** The campaign audience has no recipient. **Čo urobiť:** Change the audience. ### `expired` {#error-expired} **Význam:** The object is no longer available (an export file older than its retention). **Čo urobiť:** Create it again (POST /exports). ### `forbidden` {#error-forbidden} **Význam:** 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). **Čo urobiť:** 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` {#error-method-not-allowed} **Význam:** The path exists but not with this HTTP method. **Čo urobiť:** Check the method in this document. ### `not_found` {#error-not-found} **Význam:** The object does not exist in this company (objects of other companies answer the same). **Čo urobiť:** Check the id; list the objects first. ### `not_implemented` {#error-not-implemented} **Význam:** The feature is not available yet. **Čo urobiť:** Do not rely on it. ### `rate_limited` {#error-rate-limited} **Význam:** 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. **Čo urobiť:** Wait `Retry-After` seconds; spread requests (4 a second sustained). ### `recently_sent` {#error-recently-sent} **Význam:** 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). **Čo urobiť:** Delete it after 24 hours. A request to be forgotten (GDPR) uses POST /contacts/{id}/erase, which is never refused. ### `server` {#error-server} **Význam:** Unexpected server error. **Čo urobiť:** Retry later; the request may be repeated if it is safe to repeat. ### `suppression_locked` {#error-suppression-locked} **Význam:** The address is suppressed for another reason (bounce, complaint, unsubscribe), so the blacklist cannot be added or removed; `params.reason` names it. **Čo urobiť:** Leave it: such suppressions protect the sender and are removed only one by one (DELETE /suppressions/{email}) when the reason is gone. ### `unauthorized` {#error-unauthorized} **Význam:** 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. **Čo urobiť:** Check the key and the header (`Authorization: Bearer pst_...`). Create a new key in Nastavení › Datové zdroje › API klíče. ### `unavailable` {#error-unavailable} **Význam:** 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). **Čo urobiť:** Retry later; tell support when it persists. ### `upstream` {#error-upstream} **Význam:** An outside service failed (downloading a file by URL, the stock photo service); `params.reason` says why. **Čo urobiť:** Check the URL or retry later. ### `validation` {#error-validation} **Význam:** 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`. **Čo urobiť:** Fix the named field. For 415 `contentType` send `Content-Type: application/json`; for `body` send a JSON object. ## Limity požiadaviek • Na firmu (všetky kľúče spolu): zásobník 2 500 požiadaviek doplňovaný 4 požiadavkami za sekundu a 100 000 požiadaviek za deň. • Hlavičky každej odpovede: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (unixový čas plného zásobníka). • Po prekročení 429 `rate_limited` (v `message` názov zásobníka `per-second` alebo `daily-limit`) a `Retry-After` v sekundách. ## Limity akcií {#limity-akci} | Čo | Limit | |---|---| | Telo požiadavky JSON | 5 MB | | CSV import | súbor 64 MB a 300 000 riadkov (multipart), text v JSON 5 MB; do 1 000 riadkov prebehne hneď | | API kľúče | 20 platných na firmu; platnosť najviac 730 dní; nepoužívaný 180 dní prestane platiť | | Testovacie e-maily | 10 na kampaň alebo šablónu za 24 hodín, len na testovacie adresy | | Udalosti kontaktu (`/contact-events`) | 60 na kontakt za 10 minút | | Pridanie do zoznamu, ručný vstup do automatizácie | 1 až 1 000 kontaktov v jednej požiadavke | | Automatizácia | 300 uzlov, 600 hrán; čakanie najviac 10 rokov; najviac 10 súbežných behov kontaktu | | Segment | 8 úrovní skupín, 50 pravidiel, reťaz odkazov na segmenty najviac 5 | | Kampaň | najviac 100 ID zoznamov a segmentov v každom poli publika, 1 000 vylúčených adries; odoslanie 5 minút až 365 dní dopredu | | Účtové webhooky | 50 na firmu | | Formulár | 10 odoslaní za hodinu z IP na formulár, 3 za deň na adresu, 300 za hodinu na firmu | | Server MCP | 300 správ za minútu na token | | HTML e-mailu | 102 000 bajtov | ## Ako reagovať | Situácia | Postup | |---|---| | 400 `validation` | oprava poľa podľa `message`; neopakovať bez zmeny | | 401 | skontrolovať kľúč; neopakovať | | 403 `forbidden` | iný kľúč (rola, prístup `full`, správna firma); neopakovať | | 404 | overiť ID (objekt mohol niekto zmazať) | | 409 `conflict` | načítať objekt znovu a rozhodnúť podľa `message` | | 429 | počkať `Retry-After` sekúnd, potom opakovať | | 5xx | opakovať s rastúcim odstupom, len bezpečné operácie (pozrite [Pravidlá API](https://www.postarna.sk/docs/api/conventions#opakovani-pozadavku-a-idempotence)) | --- # História zmien API v1 sa mení len spätne kompatibilne: pribúdajú operácie, polia v odpovediach a hodnoty výčtov. Klient má neznáme polia ignorovať. Odstránenie alebo zmena významu poľa sa tu oznámi vopred. ## 13. 10. 2026 • Transakčné automatizácie (zmluvné e-maily, napríklad upomienky faktúr): pole `transactional` pri automatizáciách, spúšťač len vlastná udalosť, e-maily aj kontaktom bez súhlasu s newsletterom, bez odkazu na odhlásenie. Nové kódy problémov `transactional_node`, `transactional_trigger`, `transactional_content`. Podrobnosti v [automatizáciách](https://www.postarna.sk/docs/api/automations). • Značka `{{payment_qr}}`: obrázok QR platby z reťazca SPAYD v dátach udalosti. ## 12. 10. 2026 • Verejná dokumentácia API na `/docs/api` (po česky a po slovensky), dokument OpenAPI 3.1 na `/api/openapi.json` (aj po skupinách `?tag=`), `/llms.txt` a `/llms-full.txt` pre AI agentov. • Overené recepty (opustený košík, séria po nákupe, meniny, návrat zákazníkov, formulár s potvrdením, import, kampaň, príjem webhookov); ich požiadavky a odpovede sa pri každom teste púšťajú proti serveru. • API kompatibilné so SmartEmailingom v3 (čítanie kontaktov, zoznamov a polí, účtové webhooky), CSV štatistiky a limity požiadaviek s hlavičkami `X-RateLimit-*`. ## 8. 10. 2026 • Automatizácie v2: viac spúšťačov v jednom scenári, A/B test, odkladisko, cieľ, skok na uzol, webhook, reset, vlastné udalosti, upozornenie tímu, časové údaje a 37 podmienok kompatibilných so SmartEmailingom. • Server MCP a OAuth 2.1 pre AI asistentov. --- # Referencia API ## Contacts | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/contacts` | [List contacts (search, filters, paging)](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-list) | | POST | `/api/v1/tenants/{tenant}/contacts` | [Create a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-create) | | POST | `/api/v1/tenants/{tenant}/contacts/bulk` | [Start a bulk action over contacts in the background](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-bulk-start) | | GET | `/api/v1/tenants/{tenant}/contacts/duplicates` | [Find possible duplicate contacts](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-duplicates) | | GET | `/api/v1/tenants/{tenant}/contacts/summary` | [Count contacts by status](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-summary) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Get a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-detail) | | PATCH | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Update a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-update) | | DELETE | `/api/v1/tenants/{tenant}/contacts/{contact_id}` | [Delete a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-delete) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/activities` | [List activities of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-activities) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/activities` | [Add a manual activity (note) to a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-activity-add) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/automation-runs` | [The real journey of a contact through the automations (runs and steps)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-automation-runs) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist` | [Blacklist a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-blacklist) | | DELETE | `/api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist` | [Remove a contact from the blacklist](https://www.postarna.sk/docs/api/reference-contacts#op-contact-unblacklist) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/coupons` | [List coupons given to a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-coupons) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/erase` | [Erase a contact (GDPR, irreversible)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-erase) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/export` | [Export all data of a contact (GDPR access)](https://www.postarna.sk/docs/api/reference-contacts#op-contact-export) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/neighbors` | [Previous and next contact of a filtered list](https://www.postarna.sk/docs/api/reference-contacts#op-contact-neighbors) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes` | [List consents (purposes) of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purposes) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes` | [Record a consent (purpose) of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purpose-assign) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/purposes/{consent_id}/withdraw` | [Withdraw a consent of a contact](https://www.postarna.sk/docs/api/reference-contacts#op-contact-purpose-withdraw) | | GET | `/api/v1/tenants/{tenant}/contacts/{contact_id}/segments` | [List segments a contact belongs to](https://www.postarna.sk/docs/api/reference-contacts#op-contact-segments) | | POST | `/api/v1/tenants/{tenant}/contacts/{contact_id}/unsubscribe` | [Unsubscribe a contact from everything](https://www.postarna.sk/docs/api/reference-contacts#op-contacts-unsubscribe) | | GET | `/api/v1/tenants/{tenant}/custom-fields` | [List custom fields](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-index) | | POST | `/api/v1/tenants/{tenant}/custom-fields` | [Create a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-create) | | PATCH | `/api/v1/tenants/{tenant}/custom-fields/{field_id}` | [Update a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-update) | | DELETE | `/api/v1/tenants/{tenant}/custom-fields/{field_id}` | [Delete a custom field](https://www.postarna.sk/docs/api/reference-contacts#op-custom-fields-delete) | | GET | `/api/v1/tenants/{tenant}/purposes` | [List purposes of processing (consent types)](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-index) | | POST | `/api/v1/tenants/{tenant}/purposes` | [Create a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-create) | | PATCH | `/api/v1/tenants/{tenant}/purposes/{purpose_id}` | [Update a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-update) | | DELETE | `/api/v1/tenants/{tenant}/purposes/{purpose_id}` | [Delete a purpose of processing](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-delete) | | POST | `/api/v1/tenants/{tenant}/purposes/{purpose_id}/to-contact-list` | [Create a list of the contacts with a purpose](https://www.postarna.sk/docs/api/reference-contacts#op-purposes-to-list) | | GET | `/api/v1/tenants/{tenant}/search` | [Search contacts, campaigns, templates and more](https://www.postarna.sk/docs/api/reference-contacts#op-search) | | GET | `/api/v1/tenants/{tenant}/suppressions` | [List suppressed addresses](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-list) | | POST | `/api/v1/tenants/{tenant}/suppressions` | [Suppress an address](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-add) | | POST | `/api/v1/tenants/{tenant}/suppressions/blacklist-import` | [Import addresses to the blacklist](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-blacklist-import) | | DELETE | `/api/v1/tenants/{tenant}/suppressions/{email}` | [Remove one suppression](https://www.postarna.sk/docs/api/reference-contacts#op-suppressions-remove) | ## Lists | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/lists` | [List contact lists](https://www.postarna.sk/docs/api/reference-lists#op-lists-index) | | POST | `/api/v1/tenants/{tenant}/lists` | [Create a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-create) | | POST | `/api/v1/tenants/{tenant}/lists/merge` | [Merge lists into a new list (background)](https://www.postarna.sk/docs/api/reference-lists#op-lists-merge) | | POST | `/api/v1/tenants/{tenant}/lists/tags` | [Change labels of lists](https://www.postarna.sk/docs/api/reference-lists#op-lists-tags) | | GET | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Get a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-show) | | PATCH | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Update a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-update) | | DELETE | `/api/v1/tenants/{tenant}/lists/{list_id}` | [Delete a list (only the list, with its contacts, or keeping contacts in other lists)](https://www.postarna.sk/docs/api/reference-lists#op-lists-delete) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/autofill` | [Fill empty name day, gender and salutations of the members](https://www.postarna.sk/docs/api/reference-lists#op-lists-autofill) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/copy` | [Copy a list with its members](https://www.postarna.sk/docs/api/reference-lists#op-lists-copy) | | GET | `/api/v1/tenants/{tenant}/lists/{list_id}/members` | [List members of a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members` | [Add contacts to a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-add-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members/remove` | [Remove contacts from a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-remove-members) | | POST | `/api/v1/tenants/{tenant}/lists/{list_id}/members/unsubscribe` | [Unsubscribe contacts from a list](https://www.postarna.sk/docs/api/reference-lists#op-lists-unsubscribe-members) | ## Segments | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/segments` | [List segments](https://www.postarna.sk/docs/api/reference-segments#op-segments-index) | | POST | `/api/v1/tenants/{tenant}/segments` | [Create a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-create) | | POST | `/api/v1/tenants/{tenant}/segments/preview` | [Count the contacts of a segment definition (no save)](https://www.postarna.sk/docs/api/reference-segments#op-segments-preview) | | POST | `/api/v1/tenants/{tenant}/segments/tags` | [Change labels of segments](https://www.postarna.sk/docs/api/reference-segments#op-segments-tags) | | GET | `/api/v1/tenants/{tenant}/segments/{segment}` | [Get a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-show) | | PATCH | `/api/v1/tenants/{tenant}/segments/{segment}` | [Update a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-update) | | DELETE | `/api/v1/tenants/{tenant}/segments/{segment}` | [Delete a segment no campaign, segment or automation names](https://www.postarna.sk/docs/api/reference-segments#op-segments-delete) | | GET | `/api/v1/tenants/{tenant}/segments/{segment}/members` | [List the members of a segment](https://www.postarna.sk/docs/api/reference-segments#op-segments-members) | | POST | `/api/v1/tenants/{tenant}/segments/{segment}/recompute` | [Recompute a segment now](https://www.postarna.sk/docs/api/reference-segments#op-segments-recompute) | | POST | `/api/v1/tenants/{tenant}/segments/{segment}/to-list` | [Convert a segment into a manual list of its mailable contacts](https://www.postarna.sk/docs/api/reference-segments#op-segments-to-list) | ## Campaigns | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/campaigns` | [List campaigns](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-index) | | POST | `/api/v1/tenants/{tenant}/campaigns` | [Create a campaign (draft)](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-create) | | POST | `/api/v1/tenants/{tenant}/campaigns/audience` | [Count and explain the recipients of an audience](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-audience) | | POST | `/api/v1/tenants/{tenant}/campaigns/tags` | [Change labels of campaigns](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-tags) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Get a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-show) | | PATCH | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Update a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-update) | | DELETE | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}` | [Delete a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-delete) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/approve` | [Approve a campaign: send now or schedule](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-approve) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/cancel` | [Cancel a scheduled or paused campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-cancel) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/content` | [Get the content of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-content) | | PUT | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/content` | [Save the content of a campaign draft](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-save-content) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/pause` | [Pause a sending or scheduled campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-pause) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/preview` | [Render a campaign for one contact](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-preview) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/resume` | [Resume a paused campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-resume) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/stats` | [Statistics of a campaign by provider and domain](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-stats) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/test` | [Send a test e-mail of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-test) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Get the language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-index) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Create language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-create) | | PUT | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants` | [Change the language variants of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-arrange) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/approve` | [Approve the language variants (send or schedule)](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-approve) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/cancel` | [Cancel the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-cancel) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/pause` | [Pause the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-pause) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/preview` | [Preview the audience split of language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-preview) | | POST | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/resume` | [Resume the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-resume) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/variants/stats` | [Statistics of the language variants](https://www.postarna.sk/docs/api/reference-campaigns#op-variants-stats) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/versions` | [List saved content versions of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-versions) | | GET | `/api/v1/tenants/{tenant}/campaigns/{campaign_id}/versions/{version_id}` | [Get one content version of a campaign](https://www.postarna.sk/docs/api/reference-campaigns#op-campaigns-version) | | GET | `/api/v1/tenants/{tenant}/senders` | [List verified senders](https://www.postarna.sk/docs/api/reference-campaigns#op-senders-index) | ## Templates and content | Metóda | Cesta | Popis | |---|---|---| | POST | `/api/v1/tenants/{tenant}/content/lint` | [Check e-mail content (merge tags, links, required parts)](https://www.postarna.sk/docs/api/reference-templates#op-content-lint) | | POST | `/api/v1/tenants/{tenant}/content/spam-check` | [Antispam check of e-mail content](https://www.postarna.sk/docs/api/reference-templates#op-content-spam-check) | | GET | `/api/v1/tenants/{tenant}/editor-elements` | [List saved editor elements](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-index) | | POST | `/api/v1/tenants/{tenant}/editor-elements` | [Save an editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-create) | | PATCH | `/api/v1/tenants/{tenant}/editor-elements/{element_id}` | [Update a saved editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-update) | | DELETE | `/api/v1/tenants/{tenant}/editor-elements/{element_id}` | [Delete a saved editor element](https://www.postarna.sk/docs/api/reference-templates#op-editor-elements-delete) | | GET | `/api/v1/tenants/{tenant}/file-folders` | [List folders of the file manager](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-index) | | POST | `/api/v1/tenants/{tenant}/file-folders` | [Create a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-create) | | PATCH | `/api/v1/tenants/{tenant}/file-folders/{folder_id}` | [Rename a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-update) | | DELETE | `/api/v1/tenants/{tenant}/file-folders/{folder_id}` | [Delete a folder](https://www.postarna.sk/docs/api/reference-templates#op-file-folders-delete) | | GET | `/api/v1/tenants/{tenant}/files` | [List files of the file manager](https://www.postarna.sk/docs/api/reference-templates#op-files-index) | | POST | `/api/v1/tenants/{tenant}/files` | [Upload a file (multipart)](https://www.postarna.sk/docs/api/reference-templates#op-files-upload) | | POST | `/api/v1/tenants/{tenant}/files/stock-photo` | [Save a stock photo to the file manager](https://www.postarna.sk/docs/api/reference-templates#op-files-stock-photo) | | POST | `/api/v1/tenants/{tenant}/files/video-thumbnail` | [Create a video thumbnail image](https://www.postarna.sk/docs/api/reference-templates#op-files-video-thumbnail) | | GET | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Get a file](https://www.postarna.sk/docs/api/reference-templates#op-files-show) | | PATCH | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Rename or move a file](https://www.postarna.sk/docs/api/reference-templates#op-files-update) | | DELETE | `/api/v1/tenants/{tenant}/files/{asset_id}` | [Delete a file](https://www.postarna.sk/docs/api/reference-templates#op-files-delete) | | POST | `/api/v1/tenants/{tenant}/files/{asset_id}/picked` | [Record that a file was used](https://www.postarna.sk/docs/api/reference-templates#op-files-picked) | | GET | `/api/v1/tenants/{tenant}/footers` | [List footers](https://www.postarna.sk/docs/api/reference-templates#op-footers-index) | | POST | `/api/v1/tenants/{tenant}/footers` | [Create a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-create) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Get a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-show) | | PATCH | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Rename a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-rename) | | DELETE | `/api/v1/tenants/{tenant}/footers/{footer_id}` | [Delete a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-delete) | | PUT | `/api/v1/tenants/{tenant}/footers/{footer_id}/content` | [Save the content of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-content) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/copy` | [Copy a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-copy) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/default` | [Make a footer the default](https://www.postarna.sk/docs/api/reference-templates#op-footers-default) | | DELETE | `/api/v1/tenants/{tenant}/footers/{footer_id}/default` | [Stop using a footer as the default](https://www.postarna.sk/docs/api/reference-templates#op-footers-default-off) | | POST | `/api/v1/tenants/{tenant}/footers/{footer_id}/publish` | [Publish a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-publish) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}/versions` | [List saved versions of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-versions) | | GET | `/api/v1/tenants/{tenant}/footers/{footer_id}/versions/{version_id}` | [Get one version of a footer](https://www.postarna.sk/docs/api/reference-templates#op-footers-version) | | GET | `/api/v1/tenants/{tenant}/landing-pages` | [List landing pages](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-index) | | POST | `/api/v1/tenants/{tenant}/landing-pages` | [Create a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-create) | | GET | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Get a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-show) | | PATCH | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Update a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-update) | | DELETE | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}` | [Delete a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-delete) | | POST | `/api/v1/tenants/{tenant}/landing-pages/{landing_page_id}/copy` | [Copy a landing page](https://www.postarna.sk/docs/api/reference-templates#op-landing-pages-copy) | | GET | `/api/v1/tenants/{tenant}/script-templates` | [List script templates (Twig)](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-index) | | POST | `/api/v1/tenants/{tenant}/script-templates` | [Create a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-create) | | GET | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Get a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Update a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/script-templates/{script_id}` | [Delete a script template](https://www.postarna.sk/docs/api/reference-templates#op-script-templates-delete) | | GET | `/api/v1/tenants/{tenant}/sms-templates` | [List SMS templates](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-index) | | POST | `/api/v1/tenants/{tenant}/sms-templates` | [Create an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-create) | | GET | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Get an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Update an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}` | [Delete an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-delete) | | POST | `/api/v1/tenants/{tenant}/sms-templates/{sms_template_id}/copy` | [Copy an SMS template](https://www.postarna.sk/docs/api/reference-templates#op-sms-templates-copy) | | GET | `/api/v1/tenants/{tenant}/stock-photos` | [Search stock photos](https://www.postarna.sk/docs/api/reference-templates#op-stock-photos-search) | | GET | `/api/v1/tenants/{tenant}/stock-photos/status` | [Whether the stock photo search is available](https://www.postarna.sk/docs/api/reference-templates#op-stock-photos-status) | | GET | `/api/v1/tenants/{tenant}/surveys` | [List surveys](https://www.postarna.sk/docs/api/reference-templates#op-surveys-index) | | POST | `/api/v1/tenants/{tenant}/surveys` | [Create a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-create) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Get a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-show) | | PATCH | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Update a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-update) | | DELETE | `/api/v1/tenants/{tenant}/surveys/{survey_id}` | [Delete a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-delete) | | POST | `/api/v1/tenants/{tenant}/surveys/{survey_id}/copy` | [Copy a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-copy) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}/responses` | [List responses of a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-responses) | | GET | `/api/v1/tenants/{tenant}/surveys/{survey_id}/results` | [Summary results of a survey](https://www.postarna.sk/docs/api/reference-templates#op-surveys-results) | | GET | `/api/v1/tenants/{tenant}/templates` | [List templates](https://www.postarna.sk/docs/api/reference-templates#op-templates-index) | | POST | `/api/v1/tenants/{tenant}/templates` | [Create a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-create) | | POST | `/api/v1/tenants/{tenant}/templates/tags` | [Change labels of templates](https://www.postarna.sk/docs/api/reference-templates#op-templates-tags) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Get a template with its content](https://www.postarna.sk/docs/api/reference-templates#op-templates-show) | | PATCH | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Update template settings (name, subject, preheader ...)](https://www.postarna.sk/docs/api/reference-templates#op-templates-update) | | DELETE | `/api/v1/tenants/{tenant}/templates/{template_id}` | [Delete a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-delete) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/archive` | [Archive a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-archive) | | PUT | `/api/v1/tenants/{tenant}/templates/{template_id}/content` | [Save the content of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-save-content) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/convert-to-visual` | [Convert an HTML template to the visual editor](https://www.postarna.sk/docs/api/reference-templates#op-templates-convert-to-visual) | | DELETE | `/api/v1/tenants/{tenant}/templates/{template_id}/draft` | [Discard the unpublished draft of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-discard-draft) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/duplicate` | [Duplicate a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-duplicate) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/publish` | [Publish the draft of a template used by an active automation](https://www.postarna.sk/docs/api/reference-templates#op-templates-publish) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/test` | [Send a test e-mail of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-test) | | POST | `/api/v1/tenants/{tenant}/templates/{template_id}/unarchive` | [Restore an archived template](https://www.postarna.sk/docs/api/reference-templates#op-templates-unarchive) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}/versions` | [List saved content versions of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-versions) | | GET | `/api/v1/tenants/{tenant}/templates/{template_id}/versions/{version_id}` | [Get one content version of a template](https://www.postarna.sk/docs/api/reference-templates#op-templates-version) | | GET | `/api/v1/tenants/{tenant}/test-recipients` | [List the test addresses of the company](https://www.postarna.sk/docs/api/reference-templates#op-test-recipients) | | PUT | `/api/v1/tenants/{tenant}/test-recipients` | [Replace the test addresses of the company](https://www.postarna.sk/docs/api/reference-templates#op-test-recipients-update) | | GET | `/api/v1/tenants/{tenant}/unsubscribe-pages` | [List unsubscribe pages](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-index) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages` | [Create an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-create) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/preview` | [Render an unsubscribe page preview](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-preview) | | GET | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Get an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-show) | | PATCH | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Update an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-update) | | DELETE | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}` | [Delete an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-delete) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/copy` | [Copy an unsubscribe page](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-copy) | | POST | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/default` | [Make an unsubscribe page the default](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-default) | | DELETE | `/api/v1/tenants/{tenant}/unsubscribe-pages/{unsub_page_id}/default` | [Stop using an unsubscribe page as the default](https://www.postarna.sk/docs/api/reference-templates#op-unsubscribe-pages-default-off) | ## Automations | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/automations` | [List automations](https://www.postarna.sk/docs/api/reference-automations#op-automations-index) | | POST | `/api/v1/tenants/{tenant}/automations` | [Create an automation (draft)](https://www.postarna.sk/docs/api/reference-automations#op-automations-create) | | POST | `/api/v1/tenants/{tenant}/automations/resolve-time` | [Resolve a time spec to a moment (preview)](https://www.postarna.sk/docs/api/reference-automations#op-automations-resolve-time) | | POST | `/api/v1/tenants/{tenant}/automations/tags` | [Change labels of automations](https://www.postarna.sk/docs/api/reference-automations#op-automations-tags) | | POST | `/api/v1/tenants/{tenant}/automations/validate` | [Validate a graph without saving](https://www.postarna.sk/docs/api/reference-automations#op-automations-validate) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Get an automation with its graph and issues](https://www.postarna.sk/docs/api/reference-automations#op-automations-show) | | PATCH | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Update name, description or labels of an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-update) | | DELETE | `/api/v1/tenants/{tenant}/automations/{automation_id}` | [Delete an automation that never ran](https://www.postarna.sk/docs/api/reference-automations#op-automations-delete) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/activate` | [Activate (start) an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-activate) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/contacts` | [Add contacts by hand to a running automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-add-contacts) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/copy` | [Copy an automation as a new draft](https://www.postarna.sk/docs/api/reference-automations#op-automations-copy) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/counts` | [Live counts per node and output](https://www.postarna.sk/docs/api/reference-automations#op-automations-counts) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/editing` | [Report that the editor has a scenario open and see who else has it](https://www.postarna.sk/docs/api/reference-automations#op-automations-editing) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/editor` | [Everything the editor needs in one answer](https://www.postarna.sk/docs/api/reference-automations#op-automations-editor) | | PUT | `/api/v1/tenants/{tenant}/automations/{automation_id}/graph` | [Save the graph of an automation (new version)](https://www.postarna.sk/docs/api/reference-automations#op-automations-save-graph) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/passes` | [Contacts that went through a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-node-passes) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/release` | [Release the contacts waiting in a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-release) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/nodes/{key}/reschedule` | [Recompute the end of waiting in a node](https://www.postarna.sk/docs/api/reference-automations#op-automations-reschedule) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/pause` | [Pause an automation](https://www.postarna.sk/docs/api/reference-automations#op-automations-pause) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/report` | [Statistics of the e-mail nodes (JSON or CSV)](https://www.postarna.sk/docs/api/reference-automations#op-automations-report) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/runs` | [Run history per contact](https://www.postarna.sk/docs/api/reference-automations#op-automations-runs) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/test` | [Test the scenario on today's data (nothing is sent)](https://www.postarna.sk/docs/api/reference-automations#op-automations-test) | | POST | `/api/v1/tenants/{tenant}/automations/{automation_id}/trace` | [Trace one contact through the scenario (nothing is sent)](https://www.postarna.sk/docs/api/reference-automations#op-automations-trace) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/versions` | [List saved versions of the graph](https://www.postarna.sk/docs/api/reference-automations#op-automations-versions) | | GET | `/api/v1/tenants/{tenant}/automations/{automation_id}/versions/{version}` | [Get one saved version of the graph](https://www.postarna.sk/docs/api/reference-automations#op-automations-version) | | POST | `/api/v1/tenants/{tenant}/contact-events` | [Record an event of a contact (custom event, cart, page visit)](https://www.postarna.sk/docs/api/reference-automations#op-contact-events-create) | ## Forms | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/forms` | [List forms](https://www.postarna.sk/docs/api/reference-forms#op-forms-list) | | POST | `/api/v1/tenants/{tenant}/forms` | [Create a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-create) | | GET | `/api/v1/tenants/{tenant}/forms/doi-templates` | [List templates usable as the double opt-in e-mail](https://www.postarna.sk/docs/api/reference-forms#op-forms-doi-templates) | | POST | `/api/v1/tenants/{tenant}/forms/preview` | [Render a form preview](https://www.postarna.sk/docs/api/reference-forms#op-forms-preview) | | POST | `/api/v1/tenants/{tenant}/forms/tags` | [Change labels of forms](https://www.postarna.sk/docs/api/reference-forms#op-forms-tags) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Get a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-show) | | PATCH | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Update a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-update) | | DELETE | `/api/v1/tenants/{tenant}/forms/{form_id}` | [Delete a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-delete) | | POST | `/api/v1/tenants/{tenant}/forms/{form_id}/copy` | [Copy a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-copy) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/embed` | [Get the embed code of a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-embed) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/history` | [Change history of a form](https://www.postarna.sk/docs/api/reference-forms#op-forms-history) | | GET | `/api/v1/tenants/{tenant}/forms/{form_id}/welcome` | [Get the e-mail after a sign-up (the form's own automation)](https://www.postarna.sk/docs/api/reference-forms#op-forms-welcome) | | PUT | `/api/v1/tenants/{tenant}/forms/{form_id}/welcome` | [Switch the e-mail after a sign-up on or off](https://www.postarna.sk/docs/api/reference-forms#op-forms-welcome-save) | ## Imports and exports | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/export-fields` | [Fields an export can contain](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-export-fields) | | GET | `/api/v1/tenants/{tenant}/exports` | [List exports](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-index) | | POST | `/api/v1/tenants/{tenant}/exports` | [Start a CSV export](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-create) | | GET | `/api/v1/tenants/{tenant}/exports/{export_id}` | [Get an export](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-show) | | GET | `/api/v1/tenants/{tenant}/exports/{export_id}/download` | [Download an export (CSV)](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-exports-download) | | GET | `/api/v1/tenants/{tenant}/imports` | [List imports](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-index) | | POST | `/api/v1/tenants/{tenant}/imports` | [Start an import](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-run) | | POST | `/api/v1/tenants/{tenant}/imports/drafts` | [Start an import draft (wizard)](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-create) | | GET | `/api/v1/tenants/{tenant}/imports/drafts/{import_id}` | [Get an import draft](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-show) | | PUT | `/api/v1/tenants/{tenant}/imports/drafts/{import_id}` | [Save an import draft](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-draft-update) | | POST | `/api/v1/tenants/{tenant}/imports/files` | [Upload a CSV file for import](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-upload) | | POST | `/api/v1/tenants/{tenant}/imports/preview` | [Preview an import: mapping, counts, problems](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-preview) | | GET | `/api/v1/tenants/{tenant}/imports/{import_id}` | [Get an import with its progress and result](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-show) | | DELETE | `/api/v1/tenants/{tenant}/imports/{import_id}` | [Delete an import record](https://www.postarna.sk/docs/api/reference-imports-and-exports#op-imports-delete) | ## Orders, feeds and coupons | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/coupon-stacks` | [List coupon stacks](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-list) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks` | [Create a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-create) | | GET | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}` | [Get a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-show) | | DELETE | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}` | [Delete a coupon stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-delete) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/assign` | [Give a coupon of a stack to a contact](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-assign) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/codes` | [Add coupon codes to a stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-import) | | GET | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/coupons` | [List coupons of a stack](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-assigned) | | POST | `/api/v1/tenants/{tenant}/coupon-stacks/{stack_id}/used` | [Mark coupons as used](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-coupon-stacks-used) | | GET | `/api/v1/tenants/{tenant}/feed-articles` | [Search articles of the article feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feed-articles-search) | | GET | `/api/v1/tenants/{tenant}/feed-products` | [Search products of the product feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feed-products-search) | | GET | `/api/v1/tenants/{tenant}/feeds` | [List feeds](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-list) | | POST | `/api/v1/tenants/{tenant}/feeds` | [Create a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-create) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Get a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-show) | | PATCH | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Update a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-update) | | DELETE | `/api/v1/tenants/{tenant}/feeds/{feed_id}` | [Delete a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-delete) | | POST | `/api/v1/tenants/{tenant}/feeds/{feed_id}/import` | [Import a feed file by upload](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-import) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}/items` | [List items of a feed](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-items) | | GET | `/api/v1/tenants/{tenant}/feeds/{feed_id}/preview` | [Preview a feed (first items, detected fields)](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-preview) | | POST | `/api/v1/tenants/{tenant}/feeds/{feed_id}/refresh` | [Download and process a feed now](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-feeds-refresh) | | GET | `/api/v1/tenants/{tenant}/order-states` | [Get the order state mapping](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-order-states-show) | | PUT | `/api/v1/tenants/{tenant}/order-states` | [Replace the order state mapping](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-order-states-replace) | | GET | `/api/v1/tenants/{tenant}/orders` | [List orders](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-list) | | POST | `/api/v1/tenants/{tenant}/orders` | [Create or update an order](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-save) | | POST | `/api/v1/tenants/{tenant}/orders/paid-at` | [Maintenance: fill empty dates of payment of orders (SmartEmailing data)](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-maintenance-orders-paid-at) | | GET | `/api/v1/tenants/{tenant}/orders/{order_id}` | [Get an order](https://www.postarna.sk/docs/api/reference-orders-and-feeds#op-orders-show) | ## Statistics | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/conversions` | [Conversions summary](https://www.postarna.sk/docs/api/reference-statistics#op-conversions-summary) | | GET | `/api/v1/tenants/{tenant}/dashboard` | [Dashboard numbers](https://www.postarna.sk/docs/api/reference-statistics#op-dashboard) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}` | [Statistics of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/activity` | [Activity of an automation over time](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-activity) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/conversions` | [Conversions (orders) of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-conversions) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/heatmap` | [Click map of an automation](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-heatmap) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/recipients` | [Recipients of an automation with their events (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-recipients) | | GET | `/api/v1/tenants/{tenant}/stats/automations/{automation_id}/report` | [Report of an automation (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-automation-report) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}` | [Statistics of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/activity` | [Activity of a campaign over time](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-activity) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/conversions` | [Conversions (orders) of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-conversions) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/heatmap` | [Click map of a campaign](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-heatmap) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/recipients` | [Recipients of a campaign with their events (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-recipients) | | GET | `/api/v1/tenants/{tenant}/stats/campaigns/{campaign_id}/report` | [Report of a campaign (JSON or CSV)](https://www.postarna.sk/docs/api/reference-statistics#op-stats-campaign-report) | | GET | `/api/v1/tenants/{tenant}/stats/emails` | [E-mail statistics of campaigns and automations](https://www.postarna.sk/docs/api/reference-statistics#op-stats-emails) | ## Sending and deliverability | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/tenants/{tenant}/deliverability/dmarc` | [DMARC summary](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-dmarc) | | GET | `/api/v1/tenants/{tenant}/deliverability/dmarc/report` | [DMARC report detail](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-dmarc-report) | | GET | `/api/v1/tenants/{tenant}/deliverability/domains` | [List domains with their DNS state](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domains) | | POST | `/api/v1/tenants/{tenant}/deliverability/domains` | [Add a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-create) | | PATCH | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}` | [Update a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-update) | | DELETE | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}` | [Delete a domain](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-delete) | | POST | `/api/v1/tenants/{tenant}/deliverability/domains/{domain_id}/check` | [Check the DNS records of a domain now](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-domain-check) | | GET | `/api/v1/tenants/{tenant}/deliverability/senders` | [Senders with their authentication state](https://www.postarna.sk/docs/api/reference-sending#op-deliverability-senders) | | GET | `/api/v1/tenants/{tenant}/sending-defaults` | [Get the default settings of new campaigns (tracking parameters on or off)](https://www.postarna.sk/docs/api/reference-sending#op-sending-defaults) | | PUT | `/api/v1/tenants/{tenant}/sending-defaults` | [Set whether new campaigns start with tracking parameters](https://www.postarna.sk/docs/api/reference-sending#op-sending-defaults-update) | | GET | `/api/v1/tenants/{tenant}/sending-mode` | [Sending mode of the company (switch, limits)](https://www.postarna.sk/docs/api/reference-sending#op-sending-mode) | | POST | `/api/v1/tenants/{tenant}/sending/domains` | [Add a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-add) | | DELETE | `/api/v1/tenants/{tenant}/sending/domains/{domain_id}` | [Delete a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-delete) | | POST | `/api/v1/tenants/{tenant}/sending/domains/{domain_id}/check` | [Check a sending domain](https://www.postarna.sk/docs/api/reference-sending#op-sending-domain-check) | | POST | `/api/v1/tenants/{tenant}/sending/senders` | [Add a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-add) | | PATCH | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}` | [Update a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-update) | | DELETE | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}` | [Delete a sender](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-delete) | | POST | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/check` | [Check whether a sender address is confirmed](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-check) | | POST | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/resend` | [Send the confirmation e-mail of a sender address again](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-resend) | | GET | `/api/v1/tenants/{tenant}/sending/senders/{sender_id}/usage` | [Where a sender is used](https://www.postarna.sk/docs/api/reference-sending#op-sending-sender-usage) | | GET | `/api/v1/tenants/{tenant}/sending/setup` | [State of the sending setup (domains and senders)](https://www.postarna.sk/docs/api/reference-sending#op-sending-setup) | ## Account and settings | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v1/public/price-list` | [Public price list (no authentication)](https://www.postarna.sk/docs/api/reference-account#op-price-list) | | GET | `/api/v1/tenants/{tenant}/account-webhooks` | [List account webhooks and their events](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-index) | | POST | `/api/v1/tenants/{tenant}/account-webhooks` | [Create an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-create) | | PATCH | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}` | [Edit, switch off or on an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-update) | | DELETE | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}` | [Delete an account webhook](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-delete) | | POST | `/api/v1/tenants/{tenant}/account-webhooks/{webhook_id}/test` | [Send a test call of an account webhook now](https://www.postarna.sk/docs/api/reference-account#op-account-webhooks-test) | | GET | `/api/v1/tenants/{tenant}/billing` | [Tariff, usage and balance](https://www.postarna.sk/docs/api/reference-account#op-billing-overview) | | GET | `/api/v1/tenants/{tenant}/billing/cancel` | [What cancelling the tariff would mean](https://www.postarna.sk/docs/api/reference-account#op-billing-cancel-check) | | GET | `/api/v1/tenants/{tenant}/billing/invoices` | [List invoices](https://www.postarna.sk/docs/api/reference-account#op-billing-invoices) | | GET | `/api/v1/tenants/{tenant}/billing/invoices/{invoice_id}/pdf` | [Download an invoice (PDF)](https://www.postarna.sk/docs/api/reference-account#op-billing-invoice-pdf) | | GET | `/api/v1/tenants/{tenant}/billing/invoices/{invoice_id}/qr.svg` | [QR payment code of an invoice (SVG)](https://www.postarna.sk/docs/api/reference-account#op-billing-invoice-qr) | | GET | `/api/v1/tenants/{tenant}/billing/payments` | [List payments](https://www.postarna.sk/docs/api/reference-account#op-billing-payments) | | GET | `/api/v1/tenants/{tenant}/billing/profile` | [Get the billing profile](https://www.postarna.sk/docs/api/reference-account#op-billing-profile) | | GET | `/api/v1/tenants/{tenant}/billing/quote` | [Price of a tariff](https://www.postarna.sk/docs/api/reference-account#op-billing-quote) | | GET | `/api/v1/tenants/{tenant}/company` | [Get the company data](https://www.postarna.sk/docs/api/reference-account#op-account-company) | | PATCH | `/api/v1/tenants/{tenant}/company` | [Update the company data](https://www.postarna.sk/docs/api/reference-account#op-account-company-update) | | GET | `/api/v1/tenants/{tenant}/consent-settings` | [Consent settings of every shop](https://www.postarna.sk/docs/api/reference-account#op-consent-settings-index) | | PATCH | `/api/v1/tenants/{tenant}/consent-settings/{shop_id}` | [Update the customer exception of a shop](https://www.postarna.sk/docs/api/reference-account#op-consent-settings-update) | | GET | `/api/v1/tenants/{tenant}/grid-tags` | [Labels used in a grid](https://www.postarna.sk/docs/api/reference-account#op-grid-tags-index) | | GET | `/api/v1/tenants/{tenant}/labels` | [List labels](https://www.postarna.sk/docs/api/reference-account#op-labels-index) | | POST | `/api/v1/tenants/{tenant}/labels` | [Create a label](https://www.postarna.sk/docs/api/reference-account#op-labels-create) | | PATCH | `/api/v1/tenants/{tenant}/labels/{label_id}` | [Update a label](https://www.postarna.sk/docs/api/reference-account#op-labels-update) | | DELETE | `/api/v1/tenants/{tenant}/labels/{label_id}` | [Delete a label](https://www.postarna.sk/docs/api/reference-account#op-labels-delete) | | POST | `/api/v1/tenants/{tenant}/labels/{label_id}/assign` | [Assign a label to objects](https://www.postarna.sk/docs/api/reference-account#op-labels-assign) | | POST | `/api/v1/tenants/{tenant}/maintenance/phone-landline-mobile` | [Maintenance: move landline-stored mobile numbers to mobile (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-phone-landline-mobile) | | POST | `/api/v1/tenants/{tenant}/maintenance/se-backfill-contacts` | [Maintenance: fill empty contact fields from a SmartEmailing backup (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-se-backfill) | | POST | `/api/v1/tenants/{tenant}/maintenance/shop-enrich` | [Maintenance: fill empty contact fields from the e-shop feeds (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-shop-enrich) | | POST | `/api/v1/tenants/{tenant}/maintenance/shop-lists` | [Maintenance: rebuild the e-shop lists (dry run unless apply)](https://www.postarna.sk/docs/api/reference-account#op-maintenance-shop-lists) | | GET | `/api/v1/tenants/{tenant}/notifications` | [List notifications](https://www.postarna.sk/docs/api/reference-account#op-notifications-list) | | POST | `/api/v1/tenants/{tenant}/notifications/delete` | [Delete notifications](https://www.postarna.sk/docs/api/reference-account#op-notifications-delete) | | POST | `/api/v1/tenants/{tenant}/notifications/read` | [Mark notifications as read](https://www.postarna.sk/docs/api/reference-account#op-notifications-read) | | POST | `/api/v1/tenants/{tenant}/notifications/unread` | [Mark notifications as unread](https://www.postarna.sk/docs/api/reference-account#op-notifications-unread) | | GET | `/api/v1/tenants/{tenant}/onboarding` | [State of the onboarding wizard](https://www.postarna.sk/docs/api/reference-account#op-onboarding-show) | | PATCH | `/api/v1/tenants/{tenant}/onboarding` | [Save the onboarding wizard](https://www.postarna.sk/docs/api/reference-account#op-onboarding-update) | | GET | `/api/v1/tenants/{tenant}/rfm` | [State of the RFM analysis](https://www.postarna.sk/docs/api/reference-account#op-rfm-state) | | POST | `/api/v1/tenants/{tenant}/rfm/enable-request` | [Ask to enable the RFM analysis](https://www.postarna.sk/docs/api/reference-account#op-rfm-enable-request) | | GET | `/api/v1/tenants/{tenant}/running-actions` | [Running background actions (imports, exports ...)](https://www.postarna.sk/docs/api/reference-account#op-running-actions-index) | | GET | `/api/v1/tenants/{tenant}/shop-enrich` | [Whether order feed imports fill empty contact fields](https://www.postarna.sk/docs/api/reference-account#op-shop-enrich-state) | | PUT | `/api/v1/tenants/{tenant}/shop-enrich` | [Turn the ongoing contact data enrichment on or off](https://www.postarna.sk/docs/api/reference-account#op-shop-enrich-switch) | | GET | `/api/v1/tenants/{tenant}/shop-settings` | [Sending company data of every shop](https://www.postarna.sk/docs/api/reference-account#op-shop-settings-index) | | PATCH | `/api/v1/tenants/{tenant}/shop-settings/{shop_id}` | [Update the sending company data of a shop](https://www.postarna.sk/docs/api/reference-account#op-shop-settings-update) | | GET | `/api/v1/tenants/{tenant}/shops` | [List shops (e-shops) of the company](https://www.postarna.sk/docs/api/reference-account#op-shops) | | POST | `/api/v1/tenants/{tenant}/shops` | [Create a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-create) | | GET | `/api/v1/tenants/{tenant}/shops/{shop_id}` | [Get a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-show) | | PATCH | `/api/v1/tenants/{tenant}/shops/{shop_id}` | [Update a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-update) | | GET | `/api/v1/tenants/{tenant}/shops/{shop_id}/brand` | [Get the brand settings of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-brand) | | PUT | `/api/v1/tenants/{tenant}/shops/{shop_id}/brand` | [Replace the brand settings of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-brand-update) | | PUT | `/api/v1/tenants/{tenant}/shops/{shop_id}/contact-language` | [Set the default language of new contacts of a shop](https://www.postarna.sk/docs/api/reference-account#op-shops-contact-language) | | POST | `/api/v1/tenants/{tenant}/shops/{shop_id}/disable` | [Switch a shop off](https://www.postarna.sk/docs/api/reference-account#op-shops-disable) | | POST | `/api/v1/tenants/{tenant}/shops/{shop_id}/enable` | [Switch a shop on](https://www.postarna.sk/docs/api/reference-account#op-shops-enable) | | GET | `/api/v1/tenants/{tenant}/site-script` | [Every shop's one script line and connection state](https://www.postarna.sk/docs/api/reference-account#op-site-script-index) | | PATCH | `/api/v1/tenants/{tenant}/site-script/{shop_id}` | [Switch the checkout newsletter box of a shop](https://www.postarna.sk/docs/api/reference-account#op-site-script-update) | | POST | `/api/v1/tenants/{tenant}/site-script/{shop_id}/check` | [Test whether the script is on the shop's homepage](https://www.postarna.sk/docs/api/reference-account#op-site-script-check) | | GET | `/api/v1/tenants/{tenant}/smartemailing` | [State of the SmartEmailing migration](https://www.postarna.sk/docs/api/reference-account#op-smartemailing-state) | | GET | `/api/v1/tenants/{tenant}/smartemailing/migrations/{migration_id}` | [Get one SmartEmailing migration run](https://www.postarna.sk/docs/api/reference-account#op-smartemailing-migration) | | GET | `/api/v1/tenants/{tenant}/web-tracking` | [Web tracking state of every shop](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-index) | | GET | `/api/v1/tenants/{tenant}/web-tracking/events` | [List web tracking events](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-events) | | PATCH | `/api/v1/tenants/{tenant}/web-tracking/{shop_id}` | [Switch web tracking of a shop](https://www.postarna.sk/docs/api/reference-account#op-web-tracking-switch) | ## SmartEmailing compatible API v3 | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/v3/account-info` | [Account info (guid = tenant id for API v1)](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-account-info) | | GET | `/api/v3/check-credentials` | [Check the credentials](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-check-credentials) | | POST | `/api/v3/check-credentials` | [Check the credentials](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-check-credentials-post) | | GET | `/api/v3/contactlists` | [List contact lists](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contactlists) | | GET | `/api/v3/contactlists/{list_id}` | [Get a contact list](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contactlist) | | GET | `/api/v3/contacts` | [List contacts](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contacts) | | GET | `/api/v3/contacts/{contact_id}` | [Get a contact](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-contact) | | GET | `/api/v3/customfields` | [List custom fields](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-customfields) | | GET | `/api/v3/ping` | [Ping (no authentication)](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-ping) | | GET | `/api/v3/web-hooks` | [List account webhooks](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhooks) | | POST | `/api/v3/web-hooks` | [Register an account webhook](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhook-create-post) | | DELETE | `/api/v3/web-hooks/{webhook_id}` | [Delete an account webhook](https://www.postarna.sk/docs/api/reference-smartemailing-v3#op-se-v3-webhook-delete-delete) | ## SmartEmailing compatible CSV statistics | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/csv/list-contacts` | [Members of a list (CSV)](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-list-contacts) | | GET | `/api/csv/statistics/email/automation-email-statistic-id` | [E-mail statistic ids of automation e-mail nodes](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-automation-statistic-ids) | | GET | `/api/csv/statistics/email/automation-email-statistic-id/{automation_id}` | [E-mail statistic ids of automation e-mail nodes of one automation](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-automation-statistic-ids-one) | | GET | `/api/csv/statistics/email/{kind}-detail/{sid}` | [Per-contact events of an e-mail statistic id (sent, opened, clicked, bounced, unsubscribed)](https://www.postarna.sk/docs/api/reference-smartemailing-csv#op-se-csv-email-detail) | ## MCP server for AI assistants | Metóda | Cesta | Popis | |---|---|---| | POST | `/mcp` | [MCP JSON-RPC endpoint (Streamable HTTP, stateless)](https://www.postarna.sk/docs/api/reference-mcp#op-mcp) | ## OAuth 2.1 for AI assistants | Metóda | Cesta | Popis | |---|---|---| | GET | `/.well-known/oauth-authorization-server` | [Authorization server metadata (RFC 8414)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-server-metadata) | | GET | `/.well-known/oauth-authorization-server/mcp` | [Authorization server metadata (RFC 8414)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-server-metadata-mcp) | | GET | `/.well-known/oauth-protected-resource` | [Protected resource metadata (RFC 9728)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-protected-resource) | | GET | `/.well-known/oauth-protected-resource/mcp` | [Protected resource metadata (RFC 9728)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-protected-resource-mcp) | | GET | `/oauth/authorize` | [Authorization (browser redirect to the consent page)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-authorize) | | POST | `/oauth/register` | [Dynamic client registration (RFC 7591, at most 20 an hour per address)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-register) | | POST | `/oauth/revoke` | [Revoke a token (RFC 7009)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-revoke) | | POST | `/oauth/token` | [Tokens: authorization_code or refresh_token (access pso_... 1 hour, refresh psr_... 30 days, rotated)](https://www.postarna.sk/docs/api/reference-oauth#op-oauth-token) | ## This document | Metóda | Cesta | Popis | |---|---|---| | GET | `/api/openapi.json` | [This OpenAPI document](https://www.postarna.sk/docs/api/reference-meta#op-openapi-document) |