{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Poštárna API","version":"1.0.0","description":"Poštárna is a multi-tenant e-mail marketing platform with statistics for companies and e-shops (Czech and Slovak). This document describes every\nroute an integration can call. Guides in Czech and Slovak: https://www.postarna.cz/docs/api (index for AI agents:\nhttps://www.postarna.cz/llms.txt, everything in one Markdown file: https://www.postarna.cz/llms-full.txt).\n\n## Three APIs\n* **API v1** (`/api/v1/tenants/{tenant}/...`): the full API, the same one the Poštárna web app uses. JSON in UTF-8.\n* **SmartEmailing compatible API v3** (`/api/v3/...`) and its CSV statistics (`/api/csv/...`): the same paths,\n envelopes and errors as SmartEmailing's REST API v3, so an existing SE integration only changes the address, the\n user name and the key. Read operations plus account webhooks.\n* **MCP server** (`POST /mcp`): Model Context Protocol for AI assistants (ChatGPT, Claude, Cursor ...), OAuth 2.1 or an\n API key.\n\n## Authentication\nCreate an API key in the app: Nastavení › Datové zdroje › API klíče (Settings › Data sources › API keys). The key\n(`pst_` + 43 characters) is shown once. Send it as `Authorization: Bearer pst_...`, or as HTTP Basic with the e-mail\nof an active member of the company as the user name and the key as the password (both work on v1 and v3). A key\nworks only in its own company (tenant), with the roles it was given (never more than its creator has), and with\nscope `full` (read and write) or `read` (only routes whose permission level is read). Keys never reach the members,\ninvitations, API keys and connected apps (those need a signed-in person: 403 `forbidden` / `api_key`).\n\n`{tenant}` in v1 paths is the company's public id (a UUID). Find it with `GET /api/v3/account-info` (`data.guid`) or\nin the app on the API keys page.\n\n## Conventions (API v1)\n* IDs are strings. Times are ISO 8601 in UTC with milliseconds (`2026-09-30T08:00:00.000Z`); local calendar days of\n the company are `YYYY-MM-DD`; automation settings use local `YYYY-MM-DDTHH:MM` and `HH:MM`.\n* Money is a decimal string next to its `currency` (`\"1290.00\"`, `\"CZK\"`). CZK and EUR are never added up or\n converted: every sum is per currency.\n* Lists are paged: `page` from 1, `pageSize` 1 to 100 (default 25); the answer is `{items, total, page, pageSize}`.\n Some grids take `sort` (`name,-createdAt`, at most 3 fields, `-` = descending).\n* Request bodies of POST, PUT and PATCH are `application/json` (415 `validation` / `contentType` otherwise); CSV\n import and file upload also take `multipart/form-data`. Unknown body fields are ignored.\n* Errors: `{\"error\": {\"code\": \"...\", \"message\": \"\", \"params\": {...}}}`. `code` is stable and\n machine readable, `message` names the field or the reason, `params` carries details (for example the issues of an\n automation graph). The API never sends texts for people.\n* No idempotency keys: retry only requests that are safe to repeat (GET, PUT of a whole object, DELETE). For POST,\n read the state first (for example list the contacts by e-mail) before you retry after a timeout. Concurrent\n edits of content and automation graphs are guarded by versions (`baseVersion`, 409 `conflict` / `version`).\n\n## Limits\nPer company (all keys together): a bucket of 2 500 requests refilled with 4 requests a second, and 100 000 requests a\nday (refilled continuously). Every answer to a key carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and\n`X-RateLimit-Reset` (unix time when the bucket is full again) of the bucket nearest to running out. Over the limit:\n429 `rate_limited` with `Retry-After` (seconds). Some actions have their own limits (test e-mails 10 per day per\ncampaign or template, contact events 60 per contact in 10 minutes, MCP 300 messages a minute).\n\n## Consent and sending\nPoštárna never e-mails a contact who unsubscribed, bounced, complained or is suppressed, and campaigns only reach\ncontacts with a valid marketing consent. Sending to real recipients (approving a campaign, activating an automation)\nis irreversible: check the audience first (`POST .../campaigns/audience`, `POST .../automations/{id}/test`). Test\ne-mails go only to the company's test addresses (`GET .../test-recipients`).\n","contact":{"name":"deriverge s.r.o.","url":"https://www.postarna.cz/docs/api"},"x-guides":{"cs":"https://www.postarna.cz/docs/api","sk":"https://www.postarna.sk/docs/api","llms":"https://www.postarna.cz/llms.txt","llmsFull":"https://www.postarna.cz/llms-full.txt"}},"servers":[{"url":"https://www.postarna.cz","description":"Production (the same API answers on www.postarna.sk)"}],"security":[{"bearerAuth":[]},{"basicAuth":[]}],"tags":[{"name":"Forms","x-displayName":"Forms","description":"Sign-up forms (double opt-in): builder settings, embed code, history."}],"x-error-codes":{"conflict":{"meaning":"The change would break the state of the object. `message`: `name` (name taken), `locked` (a list bound to an e-shop), `status` (wrong state, e.g. editing a sent campaign), `recipients` (the audience changed more than 5 % since you counted it, `params.expected` and `params.actual`), `version` (stale `baseVersion`, `params.current`), `confirm` (saving a running automation needs `confirmRunning: true`), `waiting` (contacts wait in a node you remove, `params.nodes`), `runs` (deleting an automation that ran), `trigger` (no manual trigger), `limit` (too many objects).","fix":"Read the object again, then repeat with current data; for `recipients` count the audience again and send the new `expectedRecipients`."},"count_mismatch":{"meaning":"`expectedRecipients` does not match the audience.","fix":"Count again with `POST /campaigns/audience` and send the new number."},"csrf":{"meaning":"Browser session request without the CSRF header (never with an API key).","fix":"Send the API key in `Authorization` instead of cookies."},"empty_segment":{"meaning":"The campaign audience has no recipient.","fix":"Change the audience."},"expired":{"meaning":"The object is no longer available (an export file older than its retention).","fix":"Create it again (POST /exports)."},"forbidden":{"meaning":"The credentials are valid but not allowed here. `message`: `tenant` (another company in the path), `scope` (a read-only key on a write route), `api_key` (members, invitations and keys need a signed-in person), a module name (`contacts`, `campaigns`, `content`, `settings`, `billing`: the key's roles lack the level), `read_only` (support view).","fix":"Use the tenant id of the key (`GET /api/v3/account-info`), a key with scope `full`, or a key whose roles include the module (for example marketing_manager)."},"method_not_allowed":{"meaning":"The path exists but not with this HTTP method.","fix":"Check the method in this document."},"not_found":{"meaning":"The object does not exist in this company (objects of other companies answer the same).","fix":"Check the id; list the objects first."},"not_implemented":{"meaning":"The feature is not available yet.","fix":"Do not rely on it."},"rate_limited":{"meaning":"Too many requests: the company's API limit, or the limit of one action (test e-mails, contact events, sign-in attempts). `Retry-After` says after how many seconds to retry.","fix":"Wait `Retry-After` seconds; spread requests (4 a second sustained)."},"recently_sent":{"meaning":"HTTP 423: the contact cannot be deleted yet, a campaign e-mail to it is queued or went out in the last 24 hours (SmartEmailing answers the same).","fix":"Delete it after 24 hours. A request to be forgotten (GDPR) uses POST /contacts/{id}/erase, which is never refused."},"server":{"meaning":"Unexpected server error.","fix":"Retry later; the request may be repeated if it is safe to repeat."},"suppression_locked":{"meaning":"The address is suppressed for another reason (bounce, complaint, unsubscribe), so the blacklist cannot be added or removed; `params.reason` names it.","fix":"Leave it: such suppressions protect the sender and are removed only one by one (DELETE /suppressions/{email}) when the reason is gone."},"unauthorized":{"meaning":"No valid credentials: the API key is unknown, revoked, expired, idle for 180 days, its creator left the company, or the HTTP Basic user name is not an active member.","fix":"Check the key and the header (`Authorization: Bearer pst_...`). Create a new key in Nastavení › Datové zdroje › API klíče."},"unavailable":{"meaning":"A service the action needs is not available (`mail`: the mail backend refused a test e-mail, `data_key`: encryption key for webhook passwords missing).","fix":"Retry later; tell support when it persists."},"upstream":{"meaning":"An outside service failed (downloading a file by URL, the stock photo service); `params.reason` says why.","fix":"Check the URL or retry later."},"validation":{"meaning":"A parameter or body field is missing, has the wrong type or an invalid value. `message` names it (`email`, `definition.1.0.listId`, `graph` ...), `params` may carry details such as `params.issues` of an automation graph or `params.reason`.","fix":"Fix the named field. For 415 `contentType` send `Content-Type: application/json`; for `body` send a JSON object."}},"paths":{"/api/v1/tenants/{tenant}/forms":{"get":{"operationId":"forms_list","summary":"List forms","tags":["Forms"],"description":"Sign-up forms (classic or popup).\n\nContract notes (cs):\n\n`{ \"items\": [FormSummary] }`, nejnovější první. Filtr štítků `?tag=` (opakovatelný, musí sedět všechny).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Label filter; repeat for more labels."}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"x-mcp-tool":"list_forms","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FormSummary"}}},"required":["items"]}}}},"400":{"description":"`validation` (message: tag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"forms_create","summary":"Create a form","tags":["Forms"],"description":"Creates a double opt-in sign-up form.\n\nContract notes (cs):\n\nTělo `FormInput`. Povinné: `name` (1 až 100 znaků, v tenantu jedinečný), `shopId`, `listIds` (1 až 20 ručních nebo formulářových seznamů tohoto e-shopu nebo celé firmy) a text souhlasu podle `consentMode`. Odpověď 201 s `FormDetail`. Chyby: 400 `validation` s `message` = název pole (`name`, `shop`, `fields`, `listIds`, `purposeId`, `design.width`, `settings.notify`, `settings.extraPurposes.0.label` …); 409 `conflict` / `name`.","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormInput"},"examples":{"double-opt-in-create":{"summary":"docs/api-examples/double-opt-in.json create","value":{"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"}}}}}},"x-postarna-permission":{"module":"content","level":"full","keyScope":"full"},"x-mcp-tool":"create_form","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetail"},"examples":{"double-opt-in-create":{"summary":"docs/api-examples/double-opt-in.json create","value":{"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":[]}}}}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/doi-templates":{"get":{"operationId":"forms_doi_templates","summary":"List templates usable as the double opt-in e-mail","tags":["Forms"],"description":"E-mail templates with the confirmation link ({{confirmlink}}) a form may send as its double opt-in.\n\nContract notes (cs):\n\nŠablony e-mailů s `{{confirmlink}}`, které smí formulář poslat jako potvrzovací e-mail: `{ \"items\": [ { \"id\", \"name\" } ] }`.","parameters":[{"$ref":"#/components/parameters/tenant"}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DoiTemplate"}}},"required":["items"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/preview":{"post":{"operationId":"forms_preview","summary":"Render a form preview","tags":["Forms"],"description":"Contract notes (cs):\n\nTělo `FormInput`, i neuložený a neúplný (název, seznamy a účel smí chybět). Odpověď `{ \"html\" }` = celá veřejná stránka formuláře s poznámkou „Náhled“ a vypnutým tlačítkem.\n\nOprávnění: modul `content` (čtení: seznam, detail, kódy, historie, šablony a náhled; plné: změny, kopie a štítky).","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"listIds":{"type":"array","items":{"type":"string"}},"purposeId":{"type":["string","null"]},"consentText":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"submitLabel":{"type":"string"},"successUrl":{"type":"string"},"confirmedUrl":{"type":"string"},"captcha":{"type":"boolean"},"kind":{"type":"string","enum":["classic","popup","slide"]},"popup":{"type":["object","null"],"properties":{"trigger":{"type":"string","enum":["load","delay","scroll"]},"delaySeconds":{"type":"number","description":"delay: 1 to 600 seconds after the page is ready."},"scrollUnit":{"type":"string","enum":["percent","pixels"],"description":"scroll in % of the page (10 to 100) or in pixels from the top (1 to 20000, SmartEmailing)."},"scrollPercent":{"type":"number"},"scrollPixels":{"type":"number"},"repeat":{"type":"string","enum":["days","session","browser"],"description":"session = after closing hidden for the browser session, never after a sign-up; browser = again in the next\nsession, a sign-up too; days = hidden for repeatDays (1 to 365) after closing."},"repeatDays":{"type":"number"},"after":{"type":"string","enum":["redirect","thanks","close"],"description":"thanks = Děkovací okno (the thank-you message in the same dialog, closes itself after closeSeconds); close = Bez\nděkovací stránky (the dialog closes at once, \"Hotovo\" shows for 2 s); redirect needs successUrl (the whole page goes\nthere after the sign-up)."},"closeSeconds":{"type":"number","description":"Děkovací okno closes itself after 0 to 60 seconds, 0 = stays open until the visitor closes it."},"delayScope":{"type":"string","enum":["page","site"],"description":"site = the delay counts time on the whole e-shop across page views; page = each page starts again."},"mobile":{"type":"string","enum":["off","sheet"],"description":"sheet = a bottom sheet on phones and tablets; off = never there (SmartEmailing's recommended default)."},"side":{"type":"string","enum":["left","right"],"description":"Slide-in: the button at the bottom right or left."},"skipLoggedIn":{"type":"boolean","description":"Never for a signed-in Shoptet customer (dataLayer)."},"skipFromEmail":{"type":"boolean","description":"Never for visitors from a Poštárna e-mail (marker parameter emailParam or utm_source in emailSources), 365 days."},"emailParam":{"type":"string"},"emailSources":{"type":"array","items":{"type":"string"}},"skipAfterOrder":{"type":"boolean","description":"Never after an order (thank-you page address contains one of orderPatterns), 365 days."},"orderPatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"},"description":"Never on addresses containing one of these (cart, checkout)."}},"description":"Pop-up settings, completed with POPUP_DEFAULTS; ignored for a classic form."},"design":{"type":"object","properties":{"template":{"type":"string","enum":["classic","popup","slide","popup-image","popup-image-aside","slide-image"]},"style":{"type":"string","description":"- of formStyles.json."},"width":{"type":"number"},"image":{"type":"string","description":"https address of the picture, '' = none."},"imagePosition":{"type":"string","enum":["top","aside"]},"showTitle":{"type":"boolean"},"showText":{"type":"boolean"},"titleColor":{"type":"string","description":"#rrggbb or '' (the style's colour)."},"textColor":{"type":"string"},"buttonColor":{"type":"string"},"buttonTextColor":{"type":"string"},"font":{"type":"string","enum":["arial","verdana","tahoma","trebuchet","georgia","times","courier"],"description":"Písmo (core/form_builder.FONTS): fonts every device has."},"titleSize":{"type":"number","description":"px, 14 to 48 / 12 to 28 (core/form_builder.SIZE_LIMITS)."},"textSize":{"type":"number"}}},"settings":{"type":"object","properties":{"existingMode":{"type":"string","enum":["error","update","keep"]},"errorUrl":{"type":"string"},"notify":{"type":"array","items":{"type":"string"}},"newTab":{"type":"boolean"},"keepParams":{"type":"boolean"},"affiliateParam":{"type":"string"},"thanksHtml":{"type":"string"},"typoCheck":{"type":"boolean"},"doi":{"type":"boolean"},"doiTemplateId":{"type":["string","null"]},"senderName":{"type":"string"},"senderEmail":{"type":"string"},"replyTo":{"type":"string"},"doiAfter":{"type":"string","enum":["redirect","thanks"]},"doiThanksHtml":{"type":"string"},"consentMode":{"type":"string","enum":["text","checkbox"],"description":"checkbox = a required check box with consentText; text = SmartEmailing's information text with a link."},"consentLabel":{"type":"string"},"consentLinkText":{"type":"string"},"consentLinkUrl":{"type":"string"},"extraPurposes":{"type":"array","items":{"$ref":"#/components/schemas/FormExtraPurpose"}}}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"html":{"type":"string"}},"required":["html"]}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/tags":{"post":{"operationId":"forms_tags","summary":"Change labels of forms","tags":["Forms"],"description":"Contract notes (cs):\n\nŠtítky vybraných formulářů jako u ostatních gridů (`{ \"ids\", \"add\", \"remove\" }` nebo `{ \"ids\", \"tags\" }`).","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridTagsInput"}}},"description":"Required by the server: ids."},"x-postarna-permission":{"module":"content","level":"full","keyScope":"full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"number"}},"required":["updated"]}}}},"400":{"description":"`validation` (message: ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/{form_id}":{"delete":{"operationId":"forms_delete","summary":"Delete a form","tags":["Forms"],"description":"Deletes a form (its address stops working).\n\nContract notes (cs):\n\n`GET` vrací `FormDetail`. `PATCH` přijme libovolnou část `FormInput` (`settings` a `design` celé) a vrací `FormDetail`; změna typu bez `design` dostane šablonu nového typu. `DELETE` 204: adresa formuláře přestane fungovat, záznamy souhlasů zůstávají.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"x-postarna-permission":{"module":"content","level":"full","keyScope":"full"},"x-mcp-confirm":"delete","x-mcp-tool":"delete_form","responses":{"204":{"description":"No content"},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"forms_show","summary":"Get a form","tags":["Forms"],"description":"One form with its fields, consent text and public address.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"x-mcp-tool":"get_form","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetail"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"forms_update","summary":"Update a form","tags":["Forms"],"description":"Changes a form.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"listIds":{"type":"array","items":{"type":"string"}},"purposeId":{"type":["string","null"]},"consentText":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"submitLabel":{"type":"string"},"successUrl":{"type":"string"},"confirmedUrl":{"type":"string"},"captcha":{"type":"boolean"},"kind":{"type":"string","enum":["classic","popup","slide"]},"popup":{"type":["object","null"],"properties":{"trigger":{"type":"string","enum":["load","delay","scroll"]},"delaySeconds":{"type":"number","description":"delay: 1 to 600 seconds after the page is ready."},"scrollUnit":{"type":"string","enum":["percent","pixels"],"description":"scroll in % of the page (10 to 100) or in pixels from the top (1 to 20000, SmartEmailing)."},"scrollPercent":{"type":"number"},"scrollPixels":{"type":"number"},"repeat":{"type":"string","enum":["days","session","browser"],"description":"session = after closing hidden for the browser session, never after a sign-up; browser = again in the next\nsession, a sign-up too; days = hidden for repeatDays (1 to 365) after closing."},"repeatDays":{"type":"number"},"after":{"type":"string","enum":["redirect","thanks","close"],"description":"thanks = Děkovací okno (the thank-you message in the same dialog, closes itself after closeSeconds); close = Bez\nděkovací stránky (the dialog closes at once, \"Hotovo\" shows for 2 s); redirect needs successUrl (the whole page goes\nthere after the sign-up)."},"closeSeconds":{"type":"number","description":"Děkovací okno closes itself after 0 to 60 seconds, 0 = stays open until the visitor closes it."},"delayScope":{"type":"string","enum":["page","site"],"description":"site = the delay counts time on the whole e-shop across page views; page = each page starts again."},"mobile":{"type":"string","enum":["off","sheet"],"description":"sheet = a bottom sheet on phones and tablets; off = never there (SmartEmailing's recommended default)."},"side":{"type":"string","enum":["left","right"],"description":"Slide-in: the button at the bottom right or left."},"skipLoggedIn":{"type":"boolean","description":"Never for a signed-in Shoptet customer (dataLayer)."},"skipFromEmail":{"type":"boolean","description":"Never for visitors from a Poštárna e-mail (marker parameter emailParam or utm_source in emailSources), 365 days."},"emailParam":{"type":"string"},"emailSources":{"type":"array","items":{"type":"string"}},"skipAfterOrder":{"type":"boolean","description":"Never after an order (thank-you page address contains one of orderPatterns), 365 days."},"orderPatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"},"description":"Never on addresses containing one of these (cart, checkout)."}},"description":"Pop-up settings, completed with POPUP_DEFAULTS; ignored for a classic form."},"design":{"type":"object","properties":{"template":{"type":"string","enum":["classic","popup","slide","popup-image","popup-image-aside","slide-image"]},"style":{"type":"string","description":"- of formStyles.json."},"width":{"type":"number"},"image":{"type":"string","description":"https address of the picture, '' = none."},"imagePosition":{"type":"string","enum":["top","aside"]},"showTitle":{"type":"boolean"},"showText":{"type":"boolean"},"titleColor":{"type":"string","description":"#rrggbb or '' (the style's colour)."},"textColor":{"type":"string"},"buttonColor":{"type":"string"},"buttonTextColor":{"type":"string"},"font":{"type":"string","enum":["arial","verdana","tahoma","trebuchet","georgia","times","courier"],"description":"Písmo (core/form_builder.FONTS): fonts every device has."},"titleSize":{"type":"number","description":"px, 14 to 48 / 12 to 28 (core/form_builder.SIZE_LIMITS)."},"textSize":{"type":"number"}}},"settings":{"type":"object","properties":{"existingMode":{"type":"string","enum":["error","update","keep"]},"errorUrl":{"type":"string"},"notify":{"type":"array","items":{"type":"string"}},"newTab":{"type":"boolean"},"keepParams":{"type":"boolean"},"affiliateParam":{"type":"string"},"thanksHtml":{"type":"string"},"typoCheck":{"type":"boolean"},"doi":{"type":"boolean"},"doiTemplateId":{"type":["string","null"]},"senderName":{"type":"string"},"senderEmail":{"type":"string"},"replyTo":{"type":"string"},"doiAfter":{"type":"string","enum":["redirect","thanks"]},"doiThanksHtml":{"type":"string"},"consentMode":{"type":"string","enum":["text","checkbox"],"description":"checkbox = a required check box with consentText; text = SmartEmailing's information text with a link."},"consentLabel":{"type":"string"},"consentLinkText":{"type":"string"},"consentLinkUrl":{"type":"string"},"extraPurposes":{"type":"array","items":{"$ref":"#/components/schemas/FormExtraPurpose"}}}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"x-postarna-permission":{"module":"content","level":"full","keyScope":"full"},"x-mcp-tool":"update_form","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetail"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/{form_id}/copy":{"post":{"operationId":"forms_copy","summary":"Copy a form","tags":["Forms"],"description":"Vytvořit kopii formuláře: an inactive copy with a free name.\n\nContract notes (cs):\n\nVytvořit kopii formuláře: 201 `FormDetail` vypnuté kopie s volným názvem „ (kopie)“.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"x-postarna-permission":{"module":"content","level":"full","keyScope":"full"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetail"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/{form_id}/embed":{"get":{"operationId":"forms_embed","summary":"Get the embed code of a form","tags":["Forms"],"description":"The codes of Vložit do stránky: script (JavaScript, always current), url (Odkaz na webový formulář), styled (HTML), html (Minimální HTML).\n\nContract notes (cs):\n\n`{ \"script\", \"url\", \"styled\", \"html\" }` = Vložení formuláře na web: `script` (JavaScript, `popup.js` nebo `form.js`, vždy aktuální), `url` (odkaz na veřejnou stránku), `styled` (HTML se vzhledem a vlastním CSS, po změně vložit znovu), `html` (minimální HTML bez stylů; typ pop-up a vysouvací se ztratí).","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormEmbed"},"examples":{"double-opt-in-embed":{"summary":"docs/api-examples/double-opt-in.json embed","value":{"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":""}}}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/{form_id}/history":{"get":{"operationId":"forms_history","summary":"Change history of a form","tags":["Forms"],"description":"Historie vyplnění: the sign-ups of a form, newest first (?q= address, ?filledFrom= and ?filledTo= calendar days of the tenant, ?page=, ?pageSize=, ?sort=).\n\nContract notes (cs):\n\nHistorie vyplnění: `?q=` (část adresy), `?filledFrom=` a `?filledTo=` (kalendářní dny tenanta, oba včetně), `?page=`, `?pageSize=` (nejvýš 100), `?sort=` (`-filled` výchozí, `filled`, `email`, `-email`, `id`, `-id`). Odpověď `{ \"items\": [FormFill], \"total\", \"page\", \"pageSize\" }`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}},{"name":"filledFrom","in":"query","required":false,"schema":{"type":"string"}},{"name":"filledTo","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/sort"}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FormFill"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]}}}},"400":{"description":"`validation` (message: filledTo, page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tenants/{tenant}/forms/{form_id}/welcome":{"get":{"operationId":"forms_welcome","summary":"Get the e-mail after a sign-up (the form's own automation)","tags":["Forms"],"description":"E-mail po přihlášení (core/form_welcome.py): the form's own automation and its e-mail, the coupon tags of the template (?templateId= another template to check before saving) and the shop's coupon stacks.\n\nContract notes (cs):\n\nE-mail po přihlášení (`core/form_welcome.py`): formulář vlastní automatizaci (spouštěč vyplnění formuláře s jeho id, každý kontakt jednou, jeden uzel Odeslat e-mail). Najde se podle spouštěče, ručně vytvořená se převezme (žádná druhá). `GET` (`?templateId=` = ověřit jinou šablonu) vrací `{ \"enabled\", \"automation\": { \"id\", \"name\", \"status\", \"custom\" } | null, \"templateId\", \"senderId\", \"senderName\", \"replyTo\", \"template\": { \"id\", \"name\", \"couponKeys\" } | null, \"couponStackId\", \"stacks\": [ { \"id\", \"name\", \"mergeKey\", \"tag\", \"free\", \"low\" } ], \"others\" }`. `custom` = automatizace má víc uzlů, upravuje se jen v editoru automatizací. `PUT` (modul kampaně, plný přístup) s `{ \"enabled\", \"templateId\", \"senderId\", \"senderName\", \"replyTo\", \"couponStackId\" }`: zapnuto vytvoří nebo upraví automatizaci a spustí ji, vypnuto ji pozastaví. Chyby: 400 `validation` `welcome.templateId`, `welcome.coupon` (šablona nemá značku zásobníku, `tag` v detailu), `welcome.incomplete` (`issues`); 409 `conflict` `welcome.custom`, `test_only`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}},{"name":"templateId","in":"query","required":false,"schema":{"type":"string"}}],"x-postarna-permission":{"module":"content","level":"read","keyScope":"read or full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormWelcome"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"forms_welcome_save","summary":"Switch the e-mail after a sign-up on or off","tags":["Forms"],"description":"Switches the e-mail after a sign-up on (creates or adopts the form's automation, saves its e-mail and starts it) or off (pauses it). Module campaigns: it runs an automation.\n\nContract notes (cs):\n\nE-mail po přihlášení (`core/form_welcome.py`): formulář vlastní automatizaci (spouštěč vyplnění formuláře s jeho id, každý kontakt jednou, jeden uzel Odeslat e-mail). Najde se podle spouštěče, ručně vytvořená se převezme (žádná druhá). `GET` (`?templateId=` = ověřit jinou šablonu) vrací `{ \"enabled\", \"automation\": { \"id\", \"name\", \"status\", \"custom\" } | null, \"templateId\", \"senderId\", \"senderName\", \"replyTo\", \"template\": { \"id\", \"name\", \"couponKeys\" } | null, \"couponStackId\", \"stacks\": [ { \"id\", \"name\", \"mergeKey\", \"tag\", \"free\", \"low\" } ], \"others\" }`. `custom` = automatizace má víc uzlů, upravuje se jen v editoru automatizací. `PUT` (modul kampaně, plný přístup) s `{ \"enabled\", \"templateId\", \"senderId\", \"senderName\", \"replyTo\", \"couponStackId\" }`: zapnuto vytvoří nebo upraví automatizaci a spustí ji, vypnuto ji pozastaví. Chyby: 400 `validation` `welcome.templateId`, `welcome.coupon` (šablona nemá značku zásobníku, `tag` v detailu), `welcome.incomplete` (`issues`); 409 `conflict` `welcome.custom`, `test_only`.","parameters":[{"$ref":"#/components/parameters/tenant"},{"name":"form_id","in":"path","required":true,"description":"Id of the form (string of digits).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormWelcomeInput"}}}},"x-postarna-permission":{"module":"campaigns","level":"full","keyScope":"full"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormWelcome"}}}},"400":{"description":"`validation`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict` (message: welcome.custom)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pst_ API key","description":"An API key of the company: Authorization: Bearer pst_... (Nastavení › Datové zdroje › API klíče). Scope read or full, roles of the key."},"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic as SmartEmailing: user name = e-mail of an active member of the company, password = the API key."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 for MCP clients (AI assistants) only: authorization code with PKCE S256, dynamic registration.","flows":{"authorizationCode":{"authorizationUrl":"https://www.postarna.cz/oauth/authorize","tokenUrl":"https://www.postarna.cz/oauth/token","refreshUrl":"https://www.postarna.cz/oauth/token","scopes":{"read":"Read only (routes whose permission level is read).","full":"Everything the member's roles allow."}}}}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.","schema":{"type":"string","format":"uuid"}},"page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number, from 1."},"pageSize":{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page, 1 to 100."},"q":{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Search text (case and diacritics insensitive)."},"sort":{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort fields separated by commas, \"-\" = descending, at most 3 (e.g. name,-id)."}},"headers":{"X-RateLimit-Limit":{"description":"Size of the bucket nearest to running out (2 500 per second bucket or 100 000 daily).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time when that bucket is full again.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"401 unauthorized: missing, unknown, revoked, expired or idle API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"api_key"}}}}},"Forbidden":{"description":"403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"scope"}}}}},"RateLimited":{"description":"429 rate_limited: wait Retry-After seconds.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"per-second"}}}}}},"schemas":{"AutomationStatus":{"type":"string","enum":["active","draft","paused"]},"DoiTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"description":"An e-mail template with {{confirmlink}} a form may send as its double opt-in."},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["conflict","count_mismatch","csrf","empty_segment","expired","forbidden","method_not_allowed","not_found","not_implemented","rate_limited","recently_sent","server","suppression_locked","unauthorized","unavailable","upstream","validation"],"description":"Stable machine readable code (see the error catalog in the guides)."},"message":{"type":"string","description":"The field or the reason (technical, not for people), e.g. \"email\", \"definition.1.0.listId\", \"name\"."},"params":{"type":"object","additionalProperties":true,"description":"Details: issues of a graph, expected and actual counts, retryAfter ..."}}}},"examples":[{"error":{"code":"validation","message":"email"}},{"error":{"code":"conflict","message":"version","params":{"current":4}}}]},"FormDesign":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/FormTemplate"},"style":{"type":"string","description":"- of formStyles.json."},"width":{"type":"number"},"image":{"type":"string","description":"https address of the picture, '' = none."},"imagePosition":{"type":"string","enum":["top","aside"]},"showTitle":{"type":"boolean"},"showText":{"type":"boolean"},"titleColor":{"type":"string","description":"#rrggbb or '' (the style's colour)."},"textColor":{"type":"string"},"buttonColor":{"type":"string"},"buttonTextColor":{"type":"string"},"font":{"allOf":[{"$ref":"#/components/schemas/FormFont"}],"description":"Písmo (core/form_builder.FONTS): fonts every device has."},"titleSize":{"type":"number","description":"px, 14 to 48 / 12 to 28 (core/form_builder.SIZE_LIMITS)."},"textSize":{"type":"number"}},"required":["template","style","width","image","imagePosition","showTitle","showText","titleColor","textColor","buttonColor","buttonTextColor","font","titleSize","textSize"],"description":"Vzhled (step 2): core/form_builder.py DESIGN_DEFAULTS."},"FormDetail":{"type":"object","properties":{"popup":{"anyOf":[{"$ref":"#/components/schemas/PopupSettings"},{"type":"null"}],"description":"Pop-up and slide-in forms only."},"scriptUrl":{"type":["string","null"],"description":"/popup.js for a pop-up or slide-in, else null."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"},"description":"The e-mail address is always there, first and required."},"consentText":{"type":"string","description":"The operator's text next to the required check box (consentMode checkbox)."},"consentVersion":{"type":"number","description":"Grows with every change of the consent text; each sign-up records the exact text and version."},"title":{"type":"string"},"description":{"type":"string"},"submitLabel":{"type":"string","description":"Empty = the default label in the shop's language."},"successUrl":{"type":"string","description":"https:// or empty (the thank-you page)."},"confirmedUrl":{"type":"string"},"captcha":{"type":"boolean","description":"Only with a verifier of the platform (none yet: 400 captcha)."},"hostedUrl":{"type":"string","description":"https:///f//"},"design":{"$ref":"#/components/schemas/FormDesign"},"settings":{"$ref":"#/components/schemas/FormSettings"},"id":{"type":"string"},"name":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string","enum":["active","inactive"],"description":"inactive = the form takes no sign-ups (its page answers 410)."},"listIds":{"type":"array","items":{"type":"string"}},"purposeId":{"type":["string","null"],"description":"null = Bez účelu zpracování."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"kind":{"allOf":[{"$ref":"#/components/schemas/FormKind"}],"description":"classic = in the page; popup = a dialog of popup.js; slide = Vyjíždějící (a button of popup.js opens it)."},"tags":{"type":"array","items":{"type":"string"}},"fills":{"type":"number","description":"Number of sign-ups (Historie vyplnění)."},"publicId":{"type":"string"},"previewUrl":{"type":"string","description":"hostedUrl?preview=1: Náhled webového formuláře (works for an inactive form too)."}},"required":["popup","scriptUrl","fields","consentText","consentVersion","title","description","submitLabel","successUrl","confirmedUrl","captcha","hostedUrl","design","settings","id","name","shopId","status","listIds","purposeId","createdAt","updatedAt","kind","tags","fills","publicId","previewUrl"]},"FormEmbed":{"type":"object","properties":{"html":{"type":"string","description":"Minimální HTML: inputs only, no style and no script."},"styled":{"type":"string","description":"HTML: the styled form (step 2) with its CSS; re-paste after a change."},"url":{"type":"string","description":"Odkaz na webový formulář."},"script":{"type":"string","description":"JavaScript: popup.js of a pop-up or slide-in, form.js of a classic form (always current)."}},"required":["html","styled","url","script"]},"FormExtraPurpose":{"type":"object","properties":{"purposeId":{"type":"string"},"label":{"type":"string"},"linkText":{"type":"string"},"linkUrl":{"type":"string"}},"required":["purposeId","label","linkText","linkUrl"]},"FormField":{"type":"object","properties":{"field":{"$ref":"#/components/schemas/FormFieldName"},"required":{"type":"boolean"},"label":{"type":"string","description":"Empty = the default label (catalogue or custom field name)."},"error":{"type":"string","description":"Empty = the default message."},"placeholder":{"type":"string","description":"Předvyplněný text (placeholder)."}},"required":["field","required"]},"FormFieldName":{"type":"string"},"FormFill":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":["string","null"]},"email":{"type":"string"},"filledAt":{"type":"string"},"pageUrl":{"type":"string"},"affiliate":{"type":"string"}},"required":["id","contactId","email","filledAt","pageUrl","affiliate"],"description":"A sign-up of Historie vyplnění."},"FormFont":{"type":"string","enum":["arial","verdana","tahoma","trebuchet","georgia","times","courier"]},"FormInput":{"type":"object","properties":{"name":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"listIds":{"type":"array","items":{"type":"string"}},"purposeId":{"type":["string","null"]},"consentText":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"submitLabel":{"type":"string"},"successUrl":{"type":"string"},"confirmedUrl":{"type":"string"},"captcha":{"type":"boolean"},"kind":{"type":"string","enum":["classic","popup","slide"]},"popup":{"type":["object","null"],"properties":{"trigger":{"type":"string","enum":["load","delay","scroll"]},"delaySeconds":{"type":"number","description":"delay: 1 to 600 seconds after the page is ready."},"scrollUnit":{"type":"string","enum":["percent","pixels"],"description":"scroll in % of the page (10 to 100) or in pixels from the top (1 to 20000, SmartEmailing)."},"scrollPercent":{"type":"number"},"scrollPixels":{"type":"number"},"repeat":{"type":"string","enum":["days","session","browser"],"description":"session = after closing hidden for the browser session, never after a sign-up; browser = again in the next\nsession, a sign-up too; days = hidden for repeatDays (1 to 365) after closing."},"repeatDays":{"type":"number"},"after":{"type":"string","enum":["redirect","thanks","close"],"description":"thanks = Děkovací okno (the thank-you message in the same dialog, closes itself after closeSeconds); close = Bez\nděkovací stránky (the dialog closes at once, \"Hotovo\" shows for 2 s); redirect needs successUrl (the whole page goes\nthere after the sign-up)."},"closeSeconds":{"type":"number","description":"Děkovací okno closes itself after 0 to 60 seconds, 0 = stays open until the visitor closes it."},"delayScope":{"type":"string","enum":["page","site"],"description":"site = the delay counts time on the whole e-shop across page views; page = each page starts again."},"mobile":{"type":"string","enum":["off","sheet"],"description":"sheet = a bottom sheet on phones and tablets; off = never there (SmartEmailing's recommended default)."},"side":{"type":"string","enum":["left","right"],"description":"Slide-in: the button at the bottom right or left."},"skipLoggedIn":{"type":"boolean","description":"Never for a signed-in Shoptet customer (dataLayer)."},"skipFromEmail":{"type":"boolean","description":"Never for visitors from a Poštárna e-mail (marker parameter emailParam or utm_source in emailSources), 365 days."},"emailParam":{"type":"string"},"emailSources":{"type":"array","items":{"type":"string"}},"skipAfterOrder":{"type":"boolean","description":"Never after an order (thank-you page address contains one of orderPatterns), 365 days."},"orderPatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"},"description":"Never on addresses containing one of these (cart, checkout)."}},"description":"Pop-up settings, completed with POPUP_DEFAULTS; ignored for a classic form."},"design":{"type":"object","properties":{"template":{"type":"string","enum":["classic","popup","slide","popup-image","popup-image-aside","slide-image"]},"style":{"type":"string","description":"- of formStyles.json."},"width":{"type":"number"},"image":{"type":"string","description":"https address of the picture, '' = none."},"imagePosition":{"type":"string","enum":["top","aside"]},"showTitle":{"type":"boolean"},"showText":{"type":"boolean"},"titleColor":{"type":"string","description":"#rrggbb or '' (the style's colour)."},"textColor":{"type":"string"},"buttonColor":{"type":"string"},"buttonTextColor":{"type":"string"},"font":{"type":"string","enum":["arial","verdana","tahoma","trebuchet","georgia","times","courier"],"description":"Písmo (core/form_builder.FONTS): fonts every device has."},"titleSize":{"type":"number","description":"px, 14 to 48 / 12 to 28 (core/form_builder.SIZE_LIMITS)."},"textSize":{"type":"number"}}},"settings":{"type":"object","properties":{"existingMode":{"type":"string","enum":["error","update","keep"]},"errorUrl":{"type":"string"},"notify":{"type":"array","items":{"type":"string"}},"newTab":{"type":"boolean"},"keepParams":{"type":"boolean"},"affiliateParam":{"type":"string"},"thanksHtml":{"type":"string"},"typoCheck":{"type":"boolean"},"doi":{"type":"boolean"},"doiTemplateId":{"type":["string","null"]},"senderName":{"type":"string"},"senderEmail":{"type":"string"},"replyTo":{"type":"string"},"doiAfter":{"type":"string","enum":["redirect","thanks"]},"doiThanksHtml":{"type":"string"},"consentMode":{"type":"string","enum":["text","checkbox"],"description":"checkbox = a required check box with consentText; text = SmartEmailing's information text with a link."},"consentLabel":{"type":"string"},"consentLinkText":{"type":"string"},"consentLinkUrl":{"type":"string"},"extraPurposes":{"type":"array","items":{"$ref":"#/components/schemas/FormExtraPurpose"}}}},"tags":{"type":"array","items":{"type":"string"}}},"required":["name","shopId","listIds","purposeId","consentText"]},"FormKind":{"type":"string","enum":["classic","popup","slide"]},"FormSettings":{"type":"object","properties":{"existingMode":{"type":"string","enum":["error","update","keep"]},"errorUrl":{"type":"string"},"notify":{"type":"array","items":{"type":"string"}},"newTab":{"type":"boolean"},"keepParams":{"type":"boolean"},"affiliateParam":{"type":"string"},"thanksHtml":{"type":"string"},"typoCheck":{"type":"boolean"},"doi":{"type":"boolean"},"doiTemplateId":{"type":["string","null"]},"senderName":{"type":"string"},"senderEmail":{"type":"string"},"replyTo":{"type":"string"},"doiAfter":{"type":"string","enum":["redirect","thanks"]},"doiThanksHtml":{"type":"string"},"consentMode":{"type":"string","enum":["text","checkbox"],"description":"checkbox = a required check box with consentText; text = SmartEmailing's information text with a link."},"consentLabel":{"type":"string"},"consentLinkText":{"type":"string"},"consentLinkUrl":{"type":"string"},"extraPurposes":{"type":"array","items":{"$ref":"#/components/schemas/FormExtraPurpose"}}},"required":["existingMode","errorUrl","notify","newTab","keepParams","affiliateParam","thanksHtml","typoCheck","doi","doiTemplateId","senderName","senderEmail","replyTo","doiAfter","doiThanksHtml","consentMode","consentLabel","consentLinkText","consentLinkUrl","extraPurposes"],"description":"Nastavení (step 3) and Přiřadit účely zpracování: core/form_builder.py SETTINGS_DEFAULTS."},"FormSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"shopId":{"type":"string"},"status":{"type":"string","enum":["active","inactive"],"description":"inactive = the form takes no sign-ups (its page answers 410)."},"listIds":{"type":"array","items":{"type":"string"}},"purposeId":{"type":["string","null"],"description":"null = Bez účelu zpracování."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"kind":{"allOf":[{"$ref":"#/components/schemas/FormKind"}],"description":"classic = in the page; popup = a dialog of popup.js; slide = Vyjíždějící (a button of popup.js opens it)."},"tags":{"type":"array","items":{"type":"string"}},"fills":{"type":"number","description":"Number of sign-ups (Historie vyplnění)."},"publicId":{"type":"string"},"previewUrl":{"type":"string","description":"hostedUrl?preview=1: Náhled webového formuláře (works for an inactive form too)."}},"required":["id","name","shopId","status","listIds","purposeId","createdAt","updatedAt","kind","tags","fills","publicId","previewUrl"]},"FormTemplate":{"type":"string","enum":["classic","popup","slide","popup-image","popup-image-aside","slide-image"]},"FormWelcome":{"type":"object","properties":{"enabled":{"type":"boolean","description":"The own automation runs."},"automation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"custom":{"type":"boolean"}},"required":["id","name","status","custom"],"description":"custom = changed in the automation editor (more nodes): shown only, edited there."},"templateId":{"type":["string","null"]},"senderId":{"type":["string","null"]},"senderName":{"type":"string"},"replyTo":{"type":"string"},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"couponKeys":{"type":"array","items":{"type":"string"}}},"required":["id","name","couponKeys"],"description":"The template asked for (?templateId=) or the automation's one, with the coupon keys it carries."},"couponStackId":{"type":["string","null"],"description":"The stack whose tag the template carries."},"stacks":{"type":"array","items":{"$ref":"#/components/schemas/FormWelcomeStack"}},"others":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AutomationStatus"}},"required":["id","name","status"]},"description":"Other automations started by this form."}},"required":["enabled","automation","templateId","senderId","senderName","replyTo","template","couponStackId","stacks","others"],"description":"E-mail po přihlášení (core/form_welcome.py): the form's own automation (trigger form_submitted of the form, each\ncontact once, one send_email node)."},"FormWelcomeInput":{"type":"object","properties":{"enabled":{"type":"boolean"},"templateId":{"type":["string","null"]},"senderId":{"type":["string","null"]},"senderName":{"type":"string"},"replyTo":{"type":"string"},"couponStackId":{"type":["string","null"]}},"required":["enabled"]},"FormWelcomeStack":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mergeKey":{"type":"string"},"tag":{"type":"string","description":"{{coupon_}}"},"free":{"type":"number"},"low":{"type":"boolean","description":"50 or fewer free codes."}},"required":["id","name","mergeKey","tag","free","low"],"description":"A coupon stack offered for E-mail po přihlášení (its tag in the template gives every subscriber one code)."},"GridTagsInput":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids"],"description":"Bulk label change: add and remove, or tags = the new labels of every row."},"PopupAfter":{"type":"string","enum":["redirect","thanks","close"]},"PopupRepeat":{"type":"string","enum":["days","session","browser"]},"PopupSettings":{"type":"object","properties":{"trigger":{"$ref":"#/components/schemas/PopupTrigger"},"delaySeconds":{"type":"number","description":"delay: 1 to 600 seconds after the page is ready."},"scrollUnit":{"type":"string","enum":["percent","pixels"],"description":"scroll in % of the page (10 to 100) or in pixels from the top (1 to 20000, SmartEmailing)."},"scrollPercent":{"type":"number"},"scrollPixels":{"type":"number"},"repeat":{"allOf":[{"$ref":"#/components/schemas/PopupRepeat"}],"description":"session = after closing hidden for the browser session, never after a sign-up; browser = again in the next\nsession, a sign-up too; days = hidden for repeatDays (1 to 365) after closing."},"repeatDays":{"type":"number"},"after":{"allOf":[{"$ref":"#/components/schemas/PopupAfter"}],"description":"thanks = Děkovací okno (the thank-you message in the same dialog, closes itself after closeSeconds); close = Bez\nděkovací stránky (the dialog closes at once, \"Hotovo\" shows for 2 s); redirect needs successUrl (the whole page goes\nthere after the sign-up)."},"closeSeconds":{"type":"number","description":"Děkovací okno closes itself after 0 to 60 seconds, 0 = stays open until the visitor closes it."},"delayScope":{"type":"string","enum":["page","site"],"description":"site = the delay counts time on the whole e-shop across page views; page = each page starts again."},"mobile":{"type":"string","enum":["off","sheet"],"description":"sheet = a bottom sheet on phones and tablets; off = never there (SmartEmailing's recommended default)."},"side":{"type":"string","enum":["left","right"],"description":"Slide-in: the button at the bottom right or left."},"skipLoggedIn":{"type":"boolean","description":"Never for a signed-in Shoptet customer (dataLayer)."},"skipFromEmail":{"type":"boolean","description":"Never for visitors from a Poštárna e-mail (marker parameter emailParam or utm_source in emailSources), 365 days."},"emailParam":{"type":"string"},"emailSources":{"type":"array","items":{"type":"string"}},"skipAfterOrder":{"type":"boolean","description":"Never after an order (thank-you page address contains one of orderPatterns), 365 days."},"orderPatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"},"description":"Never on addresses containing one of these (cart, checkout)."}},"required":["trigger","delaySeconds","scrollUnit","scrollPercent","scrollPixels","repeat","repeatDays","after","closeSeconds","delayScope","mobile","side","skipLoggedIn","skipFromEmail","emailParam","emailSources","skipAfterOrder","orderPatterns","excludePatterns"],"description":"Settings of a pop-up or slide-in form (core/form_popup.py)."},"PopupTrigger":{"type":"string","enum":["load","delay","scroll"]}}}}