Parametry a typy

Každá šablona má schéma parametrů. Dokumentuje, co šablona očekává, pohání panel parametrů v editoru, generuje TypeScriptové typy a – což je nejdůležitější – validuje každé odeslání. Požadavek, jehož parametry neodpovídají, skončí chybou 422 invalid_template_params ještě předtím, než se spotřebuje jakýkoli kredit.

Definice parametrů

Každý parametr má:

Pole	Význam
name	Identifikátor používaný v šabloně, např. customer_name. Písmena, číslice, _ a -; povolené jsou i názvy s tečkou jako customer.name, které vytvoří vnořené objekty. frontmail, this a root jsou rezervované.
label, description	Zobrazují se v panelu parametrů a ve vygenerovaných snippetech.
type	Jeden z typů níže.
required	Chybějící (nebo prázdná) hodnota → chyba.
default	Použije se, když hodnota chybí. Parametr s výchozí hodnotou nikdy neselže jako required.
sampleValue	Používá ho náhled a testovací odeslání.
Pravidla	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields – podle typu.

V editoru otevřete Parametry a přidejte je tlačítkem Přidat parametr, nebo klikněte na Najít v šabloně: Frontmail projde HTML, předmět a pole s příjemci, najde {{placeholdery}} a pro každý navrhne parametr, včetně polí položek použitých uvnitř bloků {{#each}}.

Typy

Typ	Přijímá (JSON)	Převod z řetězců (formuláře)	Pravidla	Výstup v šabloně
string	string, number, boolean	převede se na řetězec	minLength, maxLength, pattern	escapovaný text
text	stejně jako string	stejně	stejně	escapovaný text; zalomení řádků zachováte pomocí {{nl2br x}}
email	string	ořízne se	musí být platná adresa (max. 254 znaků); maxLength, pattern	escapovaný text
url	string	ořízne se	jen http, https, mailto nebo tel	escapovaný text
number	number	"1234.5", "1 234,5" (mezery a desetinná čárka jsou povolené)	min, max	číslo (použijte formatNumber / formatMoney)
boolean	boolean, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (bez ohledu na velikost písmen)	–	true / false pro {{#if}}
date	ISO řetězec, epoch v milisekundách	YYYY-MM-DD (zůstane jako kalendářní datum) nebo YYYY-MM-DDTHH:mm… (normalizuje se na ISO v UTC)	–	řetězec (použijte formatDate)
enum	string nebo number	ořízne se	hodnota musí být v enumValues	escapovaný text
html	string	–	minLength, maxLength	sanitizované HTML, vykreslené jako markup
list	pole objektů	JSON řetězec se naparsuje	min, max položek (výchozí max. 500); každá položka se validuje podle itemFields	pole pro {{#each}}

Další pravidla:

• Prázdný řetězec nebo null se počítá jako chybějící hodnota, takže se uplatní required a default.
• Řetězcové parametry bez maxLength jsou omezené na 50 000 znaků.
• Všechny parametry dohromady smějí mít nejvýše 256 kB JSON; větší payloady selžou s chybou payload_too_large.
• pattern musí odpovídat celé hodnotě (automaticky se ukotví), např. [A-Z]{2}\d{4}.

Převod hodnot z formulářů

sendForm() a POST /v1/send-form odesílají multipart/form-data, kde je každá hodnota řetězec. Frontmail je převede podle deklarovaných typů, takže stejná šablona funguje pro JSON i formuláře:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- zaškrtnuto "on" → true; nezaškrtnuto → chybí → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" zůstane "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Pokoj","qty":1}]'> <!-- list → naparsovaný JSON -->

Souborové inputy se stanou přílohami, ne parametry.

Neznámé parametry a striktní režim

Ve výchozím stavu se parametry, které nejsou ve schématu, předají do šablony (takže můžete začít odesílat dřív, než schéma dokončíte). Zapněte Striktní parametry v Zabezpečení → Ochrana proti zneužití a místo toho se odmítnou s chybou unknown_param – doporučeno pro šablony volané s public key.

Chybová odpověď

{
  "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émů: 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. Podle param zobrazíte hlášku u správného pole formuláře; meta nese limit, takže si hlášku můžete přeložit sami.

Escapování a typ html

Každá hodnota se při vykreslení HTML-escapuje – i uvnitř {{{trojitých závorek}}}, se kterými Frontmail zachází stejně jako s {{dvojitými}}. Nikdo tak nemůže přes public key vpašovat do vašeho e-mailu markup. Pokud potřebujete formátovaný text, deklarujte parametr jako html: projde přísnou sanitizací (jen formátovací tagy, odkazy, tabulky a obrázky; žádné skripty, formuláře, iframy ani event handlery; jen bezpečné inline styly). Podrobnosti najdete v průvodci Handlebars.

V dashboardu

Panely Parametry a Ukázková data popisuje Editor šablon.