Parametre a typy

Každá šablóna má schému parametrov. Dokumentuje, čo šablóna očakáva, poháňa panel parametrov v editore, generuje typy pre TypeScript a – čo je najdôležitejšie – validuje každé odoslanie. Požiadavka, ktorej parametre nezodpovedajú schéme, zlyhá s chybou 422 invalid_template_params skôr, než sa spotrebuje akýkoľvek kredit.

Definícia parametrov

Každý parameter má:

Pole	Význam
name	Identifikátor použitý v šablóne, napr. customer_name. Písmená, číslice, _ a -; názvy s bodkou ako customer.name sú povolené a vytvárajú vnorené objekty. frontmail, this a root sú rezervované.
label, description	Zobrazujú sa v paneli parametrov a vo vygenerovaných ukážkach kódu.
type	Jeden z typov nižšie.
required	Chýbajúca (alebo prázdna) hodnota → chyba.
default	Použije sa, keď hodnota chýba. Parameter s predvolenou hodnotou nikdy nezlyhá ako povinný.
sampleValue	Používa sa v náhľade a pri testovacích odoslaniach.
Pravidlá	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields – podľa typu.

V editore otvorte Parametre a pridajte parametre tlačidlom Pridať parameter alebo kliknite na Zistiť zo šablóny: Frontmail prehľadá HTML, predmet a polia s príjemcami, nájde {{zástupné znaky}} a pre každý navrhne parameter, vrátane polí položiek použitých v blokoch {{#each}}.

Typy

Typ	Prijíma (JSON)	Prevod z reťazcov (formuláre)	Pravidlá	Výstup v šablóne
string	reťazec, číslo, boolean	prevedie sa na reťazec	minLength, maxLength, pattern	escapovaný text
text	ako string	rovnako	rovnako	escapovaný text; zalomenia riadkov zachováte cez {{nl2br x}}
email	reťazec	orezanie medzier	musí byť platná adresa (max. 254 znakov); maxLength, pattern	escapovaný text
url	reťazec	orezanie medzier	len http, https, mailto alebo tel	escapovaný text
number	číslo	"1234.5", "1 234,5" (medzery a desatinná čiarka sú povolené)	min, max	číslo (použite formatNumber / formatMoney)
boolean	boolean, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (bez ohľadu na veľkosť písmen)	–	true / false pre {{#if}}
date	reťazec ISO, epoch v milisekundách	YYYY-MM-DD (zostane kalendárnym dátumom) alebo YYYY-MM-DDTHH:mm… (normalizuje sa na ISO UTC)	–	reťazec (použite formatDate)
enum	reťazec alebo číslo	orezanie medzier	hodnota musí byť v enumValues	escapovaný text
html	reťazec	–	minLength, maxLength	vyčistené HTML, vykreslené ako značky
list	pole objektov	reťazec JSON sa naparsuje	min, max položiek (predvolené max. 500); každá položka sa validuje podľa itemFields	pole pre {{#each}}

Ďalšie pravidlá:

• Prázdny reťazec alebo null sa počíta ako chýbajúca hodnota, takže platí required a default.
• Reťazcové parametre bez maxLength sú obmedzené na 50 000 znakov.
• Všetky parametre spolu môžu mať najviac 256 kB JSON; väčšie dáta zlyhajú s chybou payload_too_large.
• pattern musí zodpovedať celej hodnote (automaticky sa ukotví), napr. [A-Z]{2}\d{4}.

Prevod hodnôt z formulárov

sendForm() a POST /v1/send-form posielajú multipart/form-data, kde je každá hodnota reťazec. Frontmail ich prevedie podľa deklarovaných typov, takže tá istá šablóna funguje pre JSON aj formuláre:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- zaškrtnuté "on" → true; nezaškrtnuté → chýba → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" zostane "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Izba","qty":1}]'> <!-- list → naparsovaný JSON -->

Súborové polia sa stanú prílohami, nie parametrami.

Neznáme parametre a prísny režim

Predvolene sa parametre, ktoré nie sú v schéme, odovzdajú šablóne (takže môžete začať posielať skôr, než schému dokončíte). Ak ich chcete namiesto toho odmietať s chybou unknown_param, zapnite Prísne parametre v časti Zabezpečenie → Ochrana pred zneužitím – odporúčame to pre šablóny používané s verejným kľúčom.

Chybová odpoveď

{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Invalid email address. message: Must be at least 10 characters.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        { "param": "email", "code": "invalid_email", "message": "Invalid email address." },
        { "param": "message", "code": "too_short", "message": "Must be at least 10 characters.", "meta": { "min": 10 } },
        { "param": "items[2].qty", "code": "too_small", "message": "Must be at least 1.", "meta": { "min": 1 } }
      ]
    }
  }
}

Kódy problémov: required, invalid_type, too_short, too_long, too_small, too_big, invalid_format, invalid_email, invalid_url, invalid_enum, invalid_date, unknown_param, payload_too_large. Podľa param zobrazíte hlásenie pri správnom poli formulára; meta nesie limit, takže si hlásenie môžete preložiť sami.

Escapovanie a typ html

Každá hodnota sa pri vykreslení escapuje do HTML – aj vnútri {{{trojitých zátvoriek}}}, ktoré Frontmail berie rovnako ako {{dvojité zátvorky}}. Nikto tak cez verejný kľúč nemôže do vášho e-mailu podstrčiť vlastné značky. Ak potrebujete formátovaný text, deklarujte parameter ako html: prejde prísnym čistením (len formátovacie značky, odkazy, tabuľky a obrázky; žiadne skripty, formuláre, iframy ani obsluhy udalostí; len bezpečné inline štýly). Podrobnosti nájdete v sprievodcovi Handlebars.

V dashboarde

Panely Parametre a Vzorové údaje popisuje Editor šablón.