Š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:

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": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.</p><p><a href=\"https://www.example.cz/kosik/\">Dokončit objednávku</a></p><p style=\"font-size:12px\">{{cl_company}}, {{cl_address}}. <a href=\"{{unsubscribe}}\">Odhlásit odběr</a></p></body></html>"
  }
}
JSON

{
  "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": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.</p><p><a href=\"https://www.example.cz/kosik/\">Dokončit objednávku</a></p><p style=\"font-size:12px\">{{cl_company}}, {{cl_address}}. <a href=\"{{unsubscribe}}\">Odhlásit odběr</a></p></body></html>",
    "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": "<presný názov šablóny>"} (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.

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": "<p>Dobrý den, {{df_jmeno}}</p>",
  "subject": "Podzimní novinky",
  "preheader": ""
}
JSON

{
  "issues": [
    {
      "code": "unknown_tag",
      "severity": "error",
      "params": {
        "tags": "{{df_jmeno}}"
      }
    },
    {
      "code": "no_unsubscribe",
      "severity": "warning",
      "params": {}
    }
  ]
}

Zástupné značky#

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:

{% set o = metadata.order %}
{% if o %}
  <p>Ďakujeme za objednávku {{ o.eshop_code }}.</p>
  <ul>{% for item in o.items %}<li>{{ item.name }}</li>{% endfor %}</ul>
{% endif %}
<p>Váš kód: <strong>{{ data.promoCode('Svátek') }}</strong></p>

• 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).

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

{
  "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.