Parameter und Typen

Jede Vorlage hat ein Parameterschema. Es dokumentiert, was die Vorlage erwartet, speist das Parameter-Panel im Editor, erzeugt TypeScript-Typen und – vor allem – validiert jede Sendung. Eine Anfrage, deren Parameter nicht passen, schlägt mit 422 invalid_template_params fehl, bevor ein Credit verbraucht wird.

Parameter definieren

Jeder Parameter hat:

Feld	Bedeutung
name	Bezeichner in der Vorlage, z. B. customer_name. Buchstaben, Ziffern, _ und -; Namen mit Punkt wie customer.name sind erlaubt und ergeben verschachtelte Objekte. frontmail, this und root sind reserviert.
label, description	Werden im Parameter-Panel und in generierten Snippets angezeigt.
type	Einer der Typen unten.
required	Fehlender (oder leerer) Wert → Fehler.
default	Wird verwendet, wenn der Wert fehlt. Ein Parameter mit Standardwert schlägt nie als required fehl.
sampleValue	Wird von der Vorschau und von Testversänden verwendet.
Regeln	minLength / maxLength, min / max, pattern (Regex), enumValues, itemFields – je nach Typ.

Öffnen Sie im Editor Parameter und fügen Sie Parameter mit Parameter hinzufügen hinzu, oder klicken Sie auf Aus Vorlage erkennen: Frontmail durchsucht HTML, Betreff und Empfängerfelder nach {{Platzhaltern}} und schlägt für jeden einen Parameter vor – einschließlich der Felder von Einträgen, die in {{#each}}-Blöcken verwendet werden.

Typen

Typ	Akzeptiert (JSON)	Umwandlung aus Strings (Formulare)	Regeln	Ausgabe in der Vorlage
string	String, Zahl, Boolean	wird in einen String umgewandelt	minLength, maxLength, pattern	maskierter Text
text	wie string	wie string	wie string	maskierter Text; mit {{nl2br x}} bleiben Zeilenumbrüche erhalten
email	String	Leerzeichen am Rand werden entfernt	muss eine gültige Adresse sein (max. 254 Zeichen); maxLength, pattern	maskierter Text
url	String	Leerzeichen am Rand werden entfernt	nur http, https, mailto oder tel	maskierter Text
number	Zahl	"1234.5", "1 234,5" (Leerzeichen und Dezimalkomma werden akzeptiert)	min, max	Zahl (verwenden Sie formatNumber / formatMoney)
boolean	Boolean, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (ohne Beachtung der Groß-/Kleinschreibung)	–	true / false für {{#if}}
date	ISO-String, Epoch-Millisekunden	YYYY-MM-DD (bleibt ein Kalenderdatum) oder YYYY-MM-DDTHH:mm… (wird auf ISO in UTC normalisiert)	–	String (verwenden Sie formatDate)
enum	String oder Zahl	Leerzeichen am Rand werden entfernt	Wert muss in enumValues enthalten sein	maskierter Text
html	String	–	minLength, maxLength	bereinigtes HTML, als Markup ausgegeben
list	Array von Objekten	ein JSON-String wird geparst	min, max Einträge (Standard max. 500); jeder Eintrag wird gegen itemFields validiert	Array für {{#each}}

Weitere Regeln:

• Ein leerer String oder null gilt als fehlend, required und default greifen also.
• String-Parameter ohne maxLength sind auf 50.000 Zeichen begrenzt.
• Alle Parameter zusammen dürfen höchstens 256 kB JSON umfassen; größere Payloads schlagen mit payload_too_large fehl.
• pattern muss auf den gesamten Wert passen (es wird automatisch verankert), z. B. [A-Z]{2}\d{4}.

Umwandlung von Formulardaten

sendForm() und POST /v1/send-form senden multipart/form-data, wo jeder Wert ein String ist. Frontmail wandelt die Werte anhand der deklarierten Typen um, sodass dieselbe Vorlage für JSON und Formulare funktioniert:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- angehakt „on“ → true; nicht angehakt → fehlt → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" bleibt "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Zimmer","qty":1}]'> <!-- list → geparstes JSON -->

Dateifelder werden zu Anhängen, nicht zu Parametern.

Unbekannte Parameter und strikter Modus

Standardmäßig werden Parameter, die nicht im Schema stehen, an die Vorlage durchgereicht (so können Sie mit dem Senden beginnen, bevor das Schema fertig ist). Aktivieren Sie Strikte Parameter unter Sicherheit → Schutz vor Missbrauch, um sie stattdessen mit dem Problem unknown_param abzulehnen – empfohlen für Vorlagen, die mit dem öffentlichen Schlüssel gesendet werden.

Die Fehlerantwort

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

Problemcodes: 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. Mit param zeigen Sie die Meldung am richtigen Formularfeld an; meta enthält das Limit, sodass Sie die Meldung selbst übersetzen können.

Maskierung und der Typ html

Jeder Wert wird beim Rendern HTML-maskiert – sogar innerhalb von {{{dreifachen Klammern}}}, die Frontmail wie {{doppelte Klammern}} behandelt. So kann niemand über einen öffentlichen Schlüssel Markup in Ihre E-Mail einschleusen. Wenn Sie formatierten Text brauchen, deklarieren Sie den Parameter als html: Er durchläuft einen strengen Sanitizer (nur Formatierungs-Tags, Links, Tabellen und Bilder; keine Skripte, Formulare, iframes oder Event-Handler; nur sichere Inline-Styles). Details im Handlebars-Leitfaden.

Im Dashboard

Die Panels „Parameter“ und „Beispieldaten“ beschreibt der Vorlageneditor.