Parametry i typy

Każdy szablon ma schemat parametrów. Opisuje, czego szablon oczekuje, zasila panel parametrów w edytorze, generuje typy TypeScript i – co najważniejsze – waliduje każdą wysyłkę. Żądanie, którego parametry nie pasują do schematu, kończy się błędem 422 invalid_template_params, zanim zostanie zużyty jakikolwiek kredyt.

Definiowanie parametrów

Każdy parametr ma:

Pole	Znaczenie
name	Identyfikator używany w szablonie, np. customer_name. Litery, cyfry, _ i -; nazwy z kropkami jak customer.name są dozwolone i tworzą zagnieżdżone obiekty. frontmail, this i root są zarezerwowane.
label, description	Wyświetlane w panelu parametrów i w generowanych fragmentach kodu.
type	Jeden z typów poniżej.
required	Brakująca (lub pusta) wartość → błąd.
default	Używana, gdy wartości brakuje. Parametr z wartością domyślną nigdy nie zgłasza błędu required.
sampleValue	Używana przez podgląd i wysyłki testowe.
Reguły	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields – zależnie od typu.

W edytorze otwórz Parametry i dodawaj parametry przyciskiem Dodaj parametr albo kliknij Wykryj z szablonu: Frontmail przeszuka HTML, temat i pola odbiorców w poszukiwaniu {{symboli zastępczych}} i zaproponuje parametr dla każdego z nich, łącznie z polami pozycji używanymi w blokach {{#each}}.

Typy

Typ	Przyjmuje (JSON)	Konwersja z tekstu (formularze)	Reguły	Wynik w szablonie
string	string, number, boolean	zamieniany na string	minLength, maxLength, pattern	escapowany tekst
text	jak string	tak samo	tak samo	escapowany tekst; żeby zachować podziały wierszy, użyj {{nl2br x}}
email	string	przycinany	musi być poprawnym adresem (maks. 254 znaki); maxLength, pattern	escapowany tekst
url	string	przycinany	tylko http, https, mailto lub tel	escapowany tekst
number	number	"1234.5", "1 234,5" (akceptowane są spacje i przecinek dziesiętny)	min, max	liczba (użyj formatNumber / formatMoney)
boolean	boolean, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (bez rozróżniania wielkości liter)	–	true / false dla {{#if}}
date	string ISO, milisekundy epoki	YYYY-MM-DD (zostaje datą kalendarzową) lub YYYY-MM-DDTHH:mm… (normalizowane do ISO UTC)	–	string (użyj formatDate)
enum	string lub number	przycinany	wartość musi być w enumValues	escapowany tekst
html	string	–	minLength, maxLength	zsanityzowany HTML, renderowany jako znaczniki
list	tablica obiektów	string JSON jest parsowany	min, max pozycji (domyślnie maks. 500); każda pozycja walidowana według itemFields	tablica dla {{#each}}

Pozostałe zasady:

• Pusty string lub null liczy się jako brak wartości, więc działają required i default.
• Parametry tekstowe bez maxLength są ograniczone do 50 000 znaków.
• Wszystkie parametry razem mogą mieć najwyżej 256 kB JSON; większe dane kończą się błędem payload_too_large.
• pattern musi pasować do całej wartości (jest zakotwiczany automatycznie), np. [A-Z]{2}\d{4}.

Konwersja wartości z formularzy

sendForm() i POST /v1/send-form wysyłają multipart/form-data, gdzie każda wartość jest stringiem. Frontmail konwertuje je według zadeklarowanych typów, więc ten sam szablon działa dla JSON i formularzy:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- zaznaczone „on” → true; niezaznaczone → brak → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" zostaje "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Pokój","qty":1}]'> <!-- list → sparsowany JSON -->

Pola plików stają się załącznikami, a nie parametrami.

Nieznane parametry i tryb ścisły

Domyślnie parametry, których nie ma w schemacie, są przekazywane do szablonu (dzięki temu możesz zacząć wysyłać, zanim dokończysz schemat). Włącz Ścisłe parametry w Bezpieczeństwo → Ochrona przed nadużyciami, żeby zamiast tego odrzucać je z błędem unknown_param – zalecane dla szablonów używanych z kluczem publicznym.

Odpowiedź z błędem

{
  "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 } }
      ]
    }
  }
}

Kody problemów: 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. Użyj param, żeby wyświetlić komunikat przy właściwym polu formularza; meta zawiera limit, więc możesz przetłumaczyć komunikat samodzielnie.

Escapowanie i typ html

Każda wartość jest przy renderowaniu escapowana jako HTML – nawet wewnątrz {{{potrójnych nawiasów}}}, które Frontmail traktuje tak samo jak {{podwójne nawiasy}}. Dzięki temu nikt nie wstrzyknie znaczników do twojego e-maila przez klucz publiczny. Jeśli potrzebujesz sformatowanego tekstu, zadeklaruj parametr jako html: przechodzi on przez ścisły sanityzer (tylko tagi formatowania, linki, tabele i obrazy; bez skryptów, formularzy, iframe’ów i obsługi zdarzeń; tylko bezpieczne style inline). Szczegóły w przewodniku po Handlebars.

W panelu

Panele Parametry i Przykładowe dane opisuje Edytor szablonów.