Variablentypen

Mailjet bietet vier Arten von Variablen an, die jeweils einen anderen Zweck in der Template-Sprache erfüllen. Zu diesen Variablentypen gehören:

1. Daten (statisch): Diese Variablen werden für statische Daten verwendet, die sich nicht häufig ändern. Dabei handelt es sich in der Regel um vordefinierte Werte.
2. Var (dynamisch): Var-Variablen werden für dynamische Daten verwendet, die sich aufgrund unterschiedlicher Bedingungen oder Eingaben ändern können.
3. Vordefinierte MJ-Variablen: Diese Variablen werden von Mailjet vordefiniert und stellen nützliche Informationen und Funktionen innerhalb der Vorlagensprache bereit.
4. Segmentierungsvariablenstrukturen: Diese Variablen werden für komplexe Segmentierungszwecke verwendet und stehen nicht im Mittelpunkt dieses Artikels.

Wir werden uns hauptsächlich auf die ersten beiden Variablentypen (data und var) konzentrieren, aber auch kurz auf vordefinierte Variablen eingehen.

Die am häufigsten verwendeten Variablentypen sind data und var. Beide dienen dem Zweck, eine Platzhalterzeichenfolge durch einen sich dynamisch ändernden Wert zu ersetzen. Sie unterscheiden sich jedoch darin, wie sie verwendet werden sollten, wie der Wert dem System zur Verfügung gestellt wird und in welchen Arten von Nachrichten sie verwendet werden können.

Zusätzlich zu den eigenständigen Variablen bietet die Templating-Sprache Werkzeuge (Funktionen), die es dem Benutzer ermöglichen, Variablen in komplexere logische und arithmetische Operationen einzubinden und die Formatierung und Kodierung zu beeinflussen. In diesem Leitfaden werden wir speziell auf die Verwendung von Funktionen wie "set" und "FormatNumberLocale" eingehen. Außerdem werden wir uns eingehend mit if-Anweisungen und for-Schleifen befassen.

 

Daten

Der Datentyp der Variablen ist vielseitig und kann sowohl in Marketing- als auch in Transaktionsnachrichten verwendet werden. Diese Flexibilität ergibt sich aus der Tatsache, dass keine Aktion seitens des Benutzers erforderlich ist, um einen Wert für den Variablenplatzhalter bereitzustellen. Stattdessen ersetzt das System den Wert automatisch basierend auf den Kontakteigenschaftenobjekten.

Ganz gleich, ob Sie eine Kampagne oder eine Transaktions-E-Mail versenden, solange die Nachricht an einen bestehenden Kontakt gerichtet ist und der Variablenname einer Kontakteigenschaft entspricht, ist das System in der Lage, die Datenvariable zu verarbeiten. Wenn der Empfänger dieser Eigenschaft einen Wert zugewiesen hat, wird dieser anstelle des variablen Platzhalters angezeigt.

 

Lassen Sie uns dies anhand eines Beispiels veranschaulichen. Angenommen, ich setze die Variable [[data:country]] im Inhalt meiner Nachricht und sende sie an einen meiner Kontakte. Bei diesem Szenario sind zwei Ergebnisse möglich:

1. Wenn für den Kontakt ein Wert für die Kontakteigenschaft "country" (Land) festgelegt ist , erhält er die Nachricht, wobei die Variable [[data:country]] durch den entsprechenden Wert ersetzt wird.
2. Wenn für den Kontakt kein Wert für die Kontakteigenschaft "country" festgelegt ist, erhält er die Nachricht ohne Ersatz für die Variable [[data:country]]. Die Variable selbst wird jedoch in der endgültigen Version der Nachricht nicht als Element der Vorlagensprache angezeigt.

Um ein konkretes Beispiel zu liefern, betrachten wir zwei Kontakte: nutzer1@domain.tld, der Frankreich als den Eigenschaftswert "country" und nutzer2@domain.tld, der keinen Wert für die Eigenschaft "country" festgelegt hat.

Wenn ich beiden dieselbe Nachricht schicke, die den Satz enthält:

„Hallo, wie geht es Ihnen jetzt in [[data:country]] nach der Pandemie?“

 

Beide Kontakte sehen unterschiedliche Inhalte:

• nutzer1@domain.tld sieht: „Hallo, wie geht es Ihnen jetzt in Frankreich nach der Pandemie?“
• nutzer2@domain.tld sieht: „Hallo, wie geht es Ihnen jetzt in nach der Pandemie?“

Im zweiten Beispiel druckt das System einfach nichts aus, weil der Benutzer keinen Wert für die zugehörige Eigenschaft der verwendeten Datenvariablen festgelegt hat.

 

Var

Es ist wichtig zu beachten, dass der Variablentyp var nicht in Marketingvorlagen oder Kampagnenentwürfen verwendet werden sollte. Obwohl es zu diesen Objekten hinzugefügt werden kann, führt der Versuch, eine solche Nachricht zu senden, aufgrund eines Fehlers in der Vorlagensprache zu einem BLOCKED-Ereignis. In der Regel weist die Fehlermeldung darauf hin, dass für die Variable var kein Wert angegeben wurde, was zu erwarten ist, da es keine Möglichkeit gibt, einen Wert dafür hinzuzufügen.

 

Es gibt jedoch Möglichkeiten, die Variablen in einer Marketingvorlage oder einer Kampagne zu verwenden. Die beiden einfachsten Ansätze sind:

• Hinzufügen der Variable var mit einem Standardwert.
• Definieren der Variablen mit Hilfe einer Set-Funktion.

Obwohl diese Ansätze technisch funktionieren, können sie kontraproduktiv und weniger nützlich sein. Der Grund dafür ist, dass Sie den Wert der Variablen vor dem Versand in der Vorlage selbst festlegen müssen, ohne dass der angezeigte Wert je nach Empfänger variieren kann. Dies widerspricht dem Zweck einer Variablen und macht ihre Flexibilität zunichte.

 

Die richtige Verwendung von var-Variablen besteht darin, sie in Transaktionsvorlagen oder direkt in den Inhalt von Transaktionsnachrichten aufzunehmen. Die zum Ersetzen dieser Variablen verwendeten Werte werden vom Benutzer je nach verwendetem Transaktionskanal über den Send-API-Aufruf (als Teil des Anforderungstexts) oder während der SMTP-Relay-Sitzung (als benutzerdefinierter Header) bereitgestellt.

Um die Variablen zu deklarieren und ihre jeweiligen Werte bereitzustellen, werden JSON-Schlüssel-Wert-Paare verwendet. Zum Beispiel "name": "Jonas" oder "testVariable123": "testValue"usw.

Im Kontext von Send API v3 wird das Objekt, das die Variablen enthält, "Vars" genannt. Für Send API v3.1 bleibt das Prinzip dasselbe, aber das Objekt heißt "Variables" (Variablen). Für per SMTP-Relay generierte Nachrichten lautet der benutzerdefinierte Header, der die JSON-codierten Variablen enthalten sollte, "X-MJ-Vars".

 

Bitte beachten Sie, dass das Mailjet-System auf bestimmte Eigenschaften angewiesen ist, die angeben, ob die Elemente der Template-Language als solche behandelt werden sollen, damit die Template-Sprache korrekt und nicht als einfacher Text verarbeitet wird. Diese Eigenschaften sind boolescher Natur. Im Folgenden finden Sie die entsprechenden Eigenschaftsnamen für jeden Transaktionskanal:

• API v3 senden: "Mj-TemplateLanguage"
• Sende-API v3.1: "TemplateLanguage"
• API v3 senden: "Mj-TemplateLanguage"

Beachten Sie, dass der Standardwert für jede dieser Eigenschaften "false" oder "0" ist. Wenn dieses Detail übersehen wird, funktionieren die Sprachvorlagen möglicherweise nicht wie erwartet, selbst wenn die Konfigurationen korrekt sind. Denn ohne die Aktivierung der oben genannten Eigenschaften interpretiert das System die Elemente der Template-Sprache in der gesendeten Nachricht als gewöhnliche Textstrings ohne zusätzliche Bedeutung.

Schließlich müssen Benutzer in einem Nischenszenario, in dem Benutzer Kampagnenentwurfsobjekte über die API erstellen und Template-Sprache im Inhalt des Kampagnenentwurfs verwenden möchten, sicherstellen, dass das mit ihrem Entwurf verknüpfte "/campaigndraft/$ID/detailcontent" -Objekt die folgende Eigenschaft im "Headers"-Objekt enthält:

Durch die Aufnahme dieser Eigenschaft erkennt das System die Verwendung von Template-Sprache im Inhalt des Kampagnenentwurfs.

 

Standardwerte 

Sowohl var- als auch data- Variablen unterstützen die Verwendung von Standardwerten. Ein Standardwert dient als Ausweich- oder Sicherheitswert, den die Benutzer unserem System beim Einrichten der Variablen in der Vorlage oder im Textkörper der Nachricht zur Verfügung stellen. Wenn bestimmte Bedingungen erfüllt sind, wird der Standardwert von unserem System angezeigt:

• Datenvariablen: Wenn für den Kontakt, der die Nachricht empfängt, kein Kontakteigenschaftswert für diese bestimmte Variable/Kontakteigenschaft festgelegt ist.
• Var-Variablen: Wenn kein Wert über den API-Aufruf oder die SMTP-Sitzung übertragen wird.

In diesen Szenarien dient der Standardwert als Ersatz, um sicherzustellen, dass immer ein Wert für die Variable angezeigt wird, auch wenn die erforderlichen Daten nicht verfügbar sind oder bereitgestellt werden.

 

Syntax

Unter Berücksichtigung der oben genannten Überlegungen wollen wir uns mit der richtigen Syntax für eigenständige Variablen befassen (Variablen, die nicht innerhalb einer Funktion verwendet werden).

 

• Var-Variablen

  • Um eine Var-Variable hinzuzufügen, verwenden Sie die folgende Syntax: {{var:variableName}}
  • So geben Sie zusammen mit der Variablen einen Standardwert an: {{var:variableName:defaultValue}}
    • Alternative Syntax: {{var:variableName:"defaultValue"}} (beide Optionen funktionieren gleich gut)
  • Um ein Leerzeichen als Standardwert auszugeben, schließen Sie es in Anführungszeichen ein: {{var:variableName:" "}}
  • Um nichts als Standardwert anzuzeigen, verwenden Sie leere Anführungszeichen: {{var:variableName:""}}

• Datenvariablen

  • Um eine Datenvariable hinzuzufügen, verwenden Sie die folgende Syntax: [[data:contactPropertyName]]
  • So stellen Sie einen Standardwert zusammen mit der Variablen bereit:[[data:contactPropertyName:defaultValue]]
    • Alternative Syntax: [[data:contactPropertyName:"defaultValue"]]

Hinweis: Während doppelte geschweifte Klammern anstelle von doppelten eckigen Klammern auch für Datenvariablen funktionieren, wird empfohlen, eckige Klammern zu verwenden, es sei denn, dies ist für bestimmte Funktionen erforderlich, die doppelte geschweifte Klammern verlangen.

 

Es ist wichtig zu beachten, dass sich das System anders verhält, wenn es auf eine Situation stößt, in der es keinen Wert für eine Datenvariable hat, als für eine var-Variable. Wenn eine Datenvariable keinen Standardwert hat und der Kontakt keinen Wert für die entsprechende Eigenschaft eingestellt hat, wird in der Nachricht ein Leerzeichen gedruckt. Wenn Sie jedoch keinen Standardwert für eine var-Variable haben und diesen nicht im API-Aufruf oder in der SMTP-Sitzung angeben, wird die Nachricht blockiert.

 

Standardwerte sind nicht obligatorisch, können aber hilfreich sein, um das Blockieren von Nachrichten zu verhindern. Wenn das System auf eine var-Variable stößt, die keinen Wert enthält, wird die Nachricht standardmäßig blockiert. Um dieses Verhalten zu beeinflussen, können Sie eine spezielle boolesche Eigenschaft in Ihren API-Aufruf oder SMTP-Header aufnehmen:

• API v3 senden: "Mj-TemplateErrorDeliver"
• Sende-API v3.1: "TemplateErrorDeliver"
• SMTP: "X-MJ-TemplateErrorDeliver"

Der Standardwert für diese Eigenschaft ist "false". Wenn Sie sie also manuell aktivieren, können Nachrichten auch dann gesendet werden, wenn Fehler in der Vorlagensprache vorliegen. Die Aktivierung dieser Eigenschaft verhindert, dass Nachrichten blockiert werden.

 

Schließlich können die Nutzer wählen, ob sie per E-Mail benachrichtigt werden möchten, wenn ihre Nachrichten aufgrund von Fehlern in der Template-Sprache blockiert werden. Dies kann durch eine weitere besondere Eigenschaft erreicht werden:

• API v3 senden: "Mj-TemplateErrorReporting" (Beispiel: "Mj-TemplateErrorReporting": "reports@domain.tld")
• API v3.1 senden: "TemplateErrorReporting" (Beispiel: {"Email": "reports@domain.tld", "Name": "Recipient Name"})
• SMTP: "X-MJ-TemplateErrorReporting" (Beispiel für einen benutzerdefinierten Header: X-MJ-TemplateErrorReporting: "reports@domain.tld")

 

Vordefinierte Variablen

In unserem System sind bestimmte Variablennamen für vordefinierte statische Variablen reserviert. Mit diesen Variablen können die Benutzer eine Variable angeben, die einem bestimmten systembasierten Wert entspricht. Zu den häufig verwendeten vordefinierten Variablen gehören:

• ID des Empfängerkontakts
• E-Mail Adresse des Empfängers
• Vorlagen-ID:
• Social-Media-Shareable-Links für die Online-Version der E-Mail (Twitter, Facebook, LinkedIn, etc.) - dies gilt für Newsletter genauso wie für die Standard-Online-Versionen/PERMALINKS.

Eine Liste dieser vordefinierten statischen Variablen finden Sie hier.

 

Die Syntax für die Verwendung einer dieser vordefinierten Variablen lautet wie folgt: {{predefinedVarHere}}.

Beispiel: {{mj:template.ID}} zeigt die Vorlagen-ID in der endgültigen Version der Nachricht an, wenn zum Senden der E-Mail eine Vorlage verwendet wurde.

 

Bitte beachten Sie, dass es weitere reservierte Variablen gibt, wie den Abmeldelink oder die Online-Version, die mit doppelten eckigen Klammern eingeleitet werden (z. B. [[PERMALINK]]). Diese Variablen werden in der Regel automatisch vom System hinzugefügt, aber die Benutzer können sie auch manuell in Drag-and-Drop-, Roh-HTML-, Roh-MJML-Vorlagen oder Kampagnenentwurfs-Detailinhaltsobjekte einfügen. Es ist wichtig zu bedenken, dass diese speziellen vordefinierten Variablen nicht mit geschweiften Klammern eingeleitet werden sollten. Wenn sie mit geschweiften Klammern eingefügt werden, behandelt das System sie als Variablen, die in einem API-Aufruf oder während einer SMTP-Sitzung (als "var"-Variablen) definiert werden müssen, und nicht als Variablen, die das System selbständig abrufen kann.

Daher muss jede vordefinierte statische Variable, die in der oben genannten Referenzdokumentation angegeben ist (beginnend mit "mj:"), mit "{{}}" eingeführt werden, während jede vordefinierte Variable, die nicht in dieser Dokumentation aufgeführt ist (die nicht mit "mj:" beginnt), mit "[[]]" eingeführt werden sollte.

 

Mehrdimensionale Objekte und mehrdimensionale Arrays

Unsere Template-Sprache erlaubt die Verwendung von mehrdimensionalen Objekten und mehrdimensionalen Arrays - diese sind zum Beispiel in verschiedenen Situationen nützlich - um Werte einzuführen, die in einer for-Schleife verwendet werden.

 

Bei einem mehrdimensionalen Objekt oder Array handelt es sich um Variablen, die untereinander verschachtelt sind. Diese sind nur in transaktionalen Vorlagen/Nachrichten verwendbar, da sie erfordern, dass die Werte vom Benutzer bereitgestellt werden, und dies muss über eine bestimmte JSON-Struktur erfolgen.

Hier ein Beispiel für eine multidimensionale Variable, die als multidimensionales Objekt in den JSON-Daten dargestellt werden muss, in denen die Variablen für diese Nachricht deklariert werden:

 

{{var:clothes.winter.coat}}

 

Jeder Punkt (".") stellt eine "Ebene" der Verschachtelung dar – der Wert ganz links gibt die äußerste Ebene an, während wir uns umso weiter nach rechts bewegen, desto weiter unten innerhalb der verschachtelten Struktur befinden wir uns. Hier ist die korrekte JSON-Struktur, die verwendet werden muss, damit unser System den Wert für den "clothes.winter.coat" richtig findet (das Beispiel enthält die v3.1-Eigenschaft "Variablen", die jedoch je nach verwendetem Transaktionskanal variieren würde, wie in einem vorherigen Abschnitt erläutert):

Die obige Einrichtung würde dazu führen, dass das Wort „Blazer“ an der Position angezeigt wird, an der "{{var:clothes.winter.coat}}" in der Vorlage/im Inhalt der E-Mail platziert wurde.

 

Mehrdimensionale Arrays werden häufiger verwendet - insbesondere in for-Schleifen (mehr dazu in einem anderen Abschnitt). Die Logik, die hinter der Strukturierung der JSON-Daten steht, wäre ähnlich wie im oben gezeigten Beispiel, mit einigen Ergänzungen (nämlich JSON-Arrays).

Hier ist ein einfaches Beispiel: {{customer.Name}}

Wenn wir uns vorstellen, dass es sich um eine Variable handelt, die in einer for-Schleife verwendet wird (was bedeutet, dass wir verschiedene Werte unter derselben Variable - in diesem Fall "Name" - zuweisen wollen), könnten wir ein Array mit verschachtelten Objekten verwenden, um dies zu erreichen. So würde das JSON aussehen:

Wie Sie sehen können, haben wir eine verschachtelte Variable namens "Name" unter der Ebene "customer" (Kunde), so dass unsere JSON-Struktur dies widerspiegeln muss. Wir definieren zuerst "customer" und geben an, dass es sich um ein Array handelt, indem wir die eckigen Klammern öffnen. Innerhalb der eckigen Klammern können wir mehrere Paare von geschweiften Klammern verwenden, um verschiedene Werte für die Variable "Name" zu definieren. Würden wir nicht ein mehrdimensionales Array verwenden (das in einem realen Szenario auch mit einer for-Schleife kombiniert würde), könnten wir die Variable "Name" nicht mehrfach mit unterschiedlichen Werten verwenden. Wir hätten etwas in der Art von "Name1", "Name2", "Name3" usw. verwenden müssen. Die Verwendung eines mehrdimensionalen Arrays spart uns also Arbeit, macht unser JSON einfacher zu verwalten und erlaubt uns gleichzeitig, dieselbe Variable Name mit verschiedenen Werten wiederzuverwenden.

Im Abschnitt For-Schleife werden wir uns ein weiteres einfaches mehrdimensionales Array sowie ein komplexeres Array (mit mehreren Verschachtelungsebenen) ansehen.

 

If-bedingte Anweisungen

Mit If-Bedingungsanweisungen werden Anforderungen eingeführt, die bestimmen, ob eine bestimmte Information angezeigt werden soll. Sie können mit Hilfe von else-Anweisungen auch alternative Werte angeben, die angezeigt werden, wenn die ursprüngliche Anforderung nicht erfüllt ist. Darüber hinaus kann eine alternative Anforderung mithilfe der bedingten Anweisung elseif eingeführt werden. Eine if-Anweisung muss mit einem endif-Operator abgeschlossen werden.

 

Typischerweise werden if-bedingte Anweisungen mithilfe von Template-Sprachblöcken in einer Drag-and-drop-Vorlage eingeführt. Sie können aber auch innerhalb von Textelementen eingefügt werden. Diese Anweisungen können sowohl in Marketing- als auch in Transaktionsvorlagen verwendet werden, wobei Transaktionsvorlagen mehr Flexibilität bieten. In einer Transaktionsvorlage können if-Bedingungen auf der Grundlage der Werte von var-Variablen, die über die Sende-API oder SMTP übertragen werden, sowie von Datenvariablen, die mit den Werten von Kontakteigenschaften arbeiten, erstellt werden. In einer Marketing-Vorlage können nur Datenvariablen verwendet werden, da es keine Möglichkeit gibt, Werte für var-Variablen zu schieben.

Hier ist ein Beispiel für eine einfache bedingte if-Anweisung, die in einer Marketing-Vorlage verwendet wird:

Hier ist ein Beispiel für die verwendete Template-Sprache:

{% if data:firstname %}
PRINT THIS IN THE MARKETING MESSAGE

{% endif %}

 

In diesem Beispiel beginnt die Template-Sprache mit einer Öffnungsklausel, die die eigentliche Bedingung enthält. Wenn die Bedingung erfüllt ist (d.h. der Empfänger hat einen Wert unter der Eigenschaft "firstname" (Vorname)), zeigt das System den Inhalt innerhalb des Blocks an ("PRINT THIS IN THE MARKETING MESSAGE"). Die Schlussklausel markiert das Ende des If-Bedingungsabschnitts.

Die If-bedingte Anweisung basiert auf einer Kontakteigenschaft ("firstname"). Das System prüft, ob der Empfänger unter der Eigenschaft "Vorname" einen Wert eingestellt hat. Wenn die Antwort ja lautet, wird das System den Inhalt des Blocks in die endgültige Version der E-Mail aufnehmen. Lautet die Antwort nein, wird die betreffende Zeichenfolge nicht angezeigt.

Hier ist ein Beispiel dafür, wie die endgültige Version der E-Mail für einen Empfänger aussehen könnte, der über die definierte Eigenschaft "firstname" verfügt :

 

Hier ist ein Beispiel der endgültigen Version der E-Mail für einen Empfänger, der keine definierte Eigenschaft "firstname" hat :

Die obige If-Bedingung prüft, ob die Eigenschaft für den Empfänger definiert ist. Sie können jedoch einen bestimmten Wert eingeben, den die Eigenschaft haben muss, damit der bedingte Inhalt gedruckt wird. Beispiel:

In diesem Beispiel wird der bedingte Inhalt "PRINT THIS IN THE MARKETING MESSAGE" nur dann in der Version der Nachricht für den Empfänger erscheinen, wenn die Kontakteigenschaft "firstname" auf den Wert "Gina" gesetzt ist. Diese Bedingung stellt sicher, dass der Inhalt ausschließlich für Empfänger angezeigt wird, deren Eigenschaft "firstname" mit dem angegebenen Wert "Gina" übereinstimmt.

 

Schauen wir uns einige Beispiele für Transaktionsvorlagen genauer an. Diese Beispiele veranschaulichen die Verwendung von var-Variablen und Template-Sprachelementenund können in Textblöcken oder Template-Sprachblöcken angewendet werden.

 

Beispiel 1: Verwendung einer var-Variable in einer Transaktionsvorlage

In diesem Beispiel wird geprüft, ob die var "variable" definiert ist. Die Bedingung ist entweder wahr oder falsch und wirkt wie eine boolesche Eigenschaft.

 

Hier erfahren Sie, was Sie in verschiedenen Szenarien erwarten können:

• Wenn die "variable" var im Aufruf der Sende-API (SAPI) oder der SMTP-Sitzung nicht definiert ist, führt dies zu einem Fehler in der Template-Sprache. Durch Hinzufügen eines Standardwertes in der if-Bedingung (var:variable:defaultValueHere) wird bei Empfängern, bei denen die Variable nicht definiert ist, immer "PRINT THIS STRING IN THE TRANSACTIONAL EMAIL" gezeigt.
• Wenn die Variable im SAPI-Aufruf oder in der SMTP-Sitzung auf "true" gesetzt ist, ist die Bedingung erfüllt.
• Wenn die Variable im SAPI-Aufruf oder in der SMTP-Sitzung auf "anyValueYouCanThinkOfOtherThanFalse" gesetzt ist, ist die Bedingung erfüllt.
• Wenn die Variable im SAPI-Aufruf oder in der SMTP-Sitzung auf "false" gesetzt ist, wird die Bedingung NICHT erfüllt. Beachten Sie den Unterschied zwischen "variable": "false" (vorheriges Szenario) und "variable": false (aktuelles Szenario).

Beispiel 2: Beispiel für andere Vergleichs- und logische Operatoren (else, elseif und ifelse + AND)

Dieses Beispiel demonstriert die Verwendung verschiedener Vergleichsoperatoren und logischer Operatoren. Sie umfasst die if-, else- und elseif-Anweisungen in Kombination mit dem logischen Operator AND.

Zum Schluss noch ein Screenshot zur Veranschaulichung 

Diese Beispiele veranschaulichen, wie var-Variablen und verschiedene Operatoren innerhalb von Transaktionsvorlagen effektiv genutzt werden können, um den Inhalt auf der Grundlage bestimmter Bedingungen anzupassen.

 

Untersuchen wir nun JSON-Datenpaare und die entsprechenden Ergebnisse, die sie für den Endempfänger liefern:

JSON 1:

JSON 2:

JSON 3:

JSON 4:

Damit der Wert "I'll consider going out" angezeigt wird, müssen folgende Bedingungen gleichzeitig erfüllt sein: Das "weather" darf nicht "bad" sein, der Wert "bankAccountBalance" muss ungleich 0 sein, und die Variable "haveFreeTime" muss wahr (oder definiert) sein. Wenn eine dieser drei Bedingungen nicht erfüllt ist, wird der Wert "I won't be going out" oder "I'll stay at home" angezeigt, je nachdem, welche Bedingung nicht erfüllt ist.

 

Bitte beachten Sie die Verwendung des logischen Operators AND, der die Verwendung von Klammern () erforderlich macht, um die richtige Gruppierung der Bedingungen zu gewährleisten.

 

For-Schleifen

Mit For-Schleifen können Sie mehrere Iterationen einer Variablen durchlaufen oder eine Liste von Variablen in einer Schleife durchlaufen, was Flexibilität und dynamische Inhalte ermöglicht. Es ist wichtig zu beachten, dass for-Schleifen nur in Transaktionsvorlagen und nicht in Marketingvorlagen verwendet werden sollten, da die Werte oder Iterationen nicht in eine Marketingnachricht eingeführt werden können.

 

Werfen wir einen Blick auf eine einfache Darstellung einer for-Schleife:

In diesem Beispiel definieren wir eine for-Schleife mit dem Variablennamen "Test" und geben den Namespace an, in dem das System nach der Variable suchen soll (var:Test). Wir gehen von einer einfachen Variable mit einer Iteration aus. Der API-Aufruf oder die SMTP-Header sollten die folgende JSON-Struktur enthalten:

Bitte beachten Sie, dass der vorhergehende Abschnitt "Mehrdimensionale Arrays" eine alternative Art der Darstellung der gleichen Art von Struktur enthält, die auch mit for-Schleifen verwendet werden kann.

 

Die for-Schleife wird durch die in der JSON-Struktur angegebenen Werte ersetzt. Hier ist ein Beispiel dafür, wie die Nachricht aussehen würde.

Stellen wir uns nun ein Szenario vor, in dem Sie zum Team für Öffentlichkeitsarbeit eines Unternehmens gehören und eine E-Mail an die Finanzabteilung senden müssen. Sie möchten die Namen, das Land des Wohnsitzes und die Telefonnummern von drei Kunden mitteilen, die bei einem Gewinnspiel Ihres Unternehmens gewonnen haben und deren Kontaktdaten vom Finanzteam überprüft werden sollen.

Um dies zu erreichen, können Sie eine for-Schleife in Ihrer Nachricht verwenden, um verschiedene Iterationen desselben Variablennamens (z. B. Name, Phone, usw.) zu durchlaufen und jedes Mal andere Werte anzeigen zu lassen.

Hier ist ein Beispiel dafür, wie Sie eine solche Template-Sprache einrichten können:

In diesem Fall verwenden wir den Variablennamen "customer", um die im API-Aufruf oder in den SMTP-Headern angegebenen Kundendaten durchzugehen. Die JSON-Struktur sollte diesem Format entsprechen:

Mit diesem Ansatz vereinfachen Sie die JSON-Struktur und verringern das Fehlerrisiko. In der daraus resultierenden E-Mail werden die Kundendaten auf der Grundlage der angegebenen Wiederholungen angezeigt.

Zum Schluss wollen wir ein komplexeres Beispiel mit einer mehrdimensionalen Array-Struktur untersuchen. In diesem Fall gehen wir von einem Szenario aus, das sich auf Winterbekleidung bezieht.

Hier ist die Konfiguration für die for-Schleife in der Vorlage:

In diesem Beispiel verwenden wir die Variable "value", die sich im Namensraum "items" in der JSON-Struktur befindet. Wir spezifizieren zwei Arten von Gegenständen (Mäntel und Hüte) mit ihren jeweiligen Variablen, die unter mehreren Ebenen von Variablen verschachtelt sind.

So würde die JSON-Struktur für dieses Beispiel aussehen:

Die resultierende Nachricht würde die Werte für den Wintermantel und die Mütze auf der Grundlage der angegebenen Wiederholungen anzeigen.

Durch die Verwendung von for-Schleifen können Sie dynamisch durch Variablen iterieren und personalisierte Inhalte in Transaktionsvorlagen generieren. Es ist wichtig, die richtige JSON-Struktur sicherzustellen und die Syntax der Vorlagensprache zu befolgen, um die gewünschten Ergebnisse zu erzielen.

 

Tabelle mit den wichtigsten Erkenntnissen aus der If-Anweisung und den For-Schleifen:

 

Textblöcke – HTML-Blöcke – Template-Sprachblöcke

Bei der Arbeit mit E-Mail-Vorlagen gibt es verschiedene Ansätze, um die Sprachstrukturen der Vorlagen einzubinden. Sie können über Textblöcke, HTML-Blöcke oder Template-Sprachblöcke in DnD-Transaktionsvorlagen eingeführt werden. Außerdem können sie direkt in den Inhalt der E-Mail eingebettet werden.

Im Allgemeinen ist es ratsam, den rohen HTML-Inhalt von den Strukturen der Template-Sprache zu trennen, wann immer dies möglich ist. Wenn es notwendig ist, sie zu kombinieren, z. B. bei der Erstellung einer Tabelle mit variablen Iterationen unter Verwendung einer for-Schleife, ist es im Allgemeinen sicherer, einen HTML-DnD-Block zu verwenden und die Template-Sprache darin zu integrieren, als rohes HTML zu einem Template-Sprachblock hinzuzufügen.

Blöcke in der Template-Sprache sind besonders nützlich bei der Arbeit mit Wenn-Bedingungs-Anweisungen. Jeder Operator innerhalb der If-Bedingung kann in einem separaten Template-Sprachblock platziert werden, wobei verschiedene andere DnD-Elemente als Inhalt dienen, der auf der Grundlage einer bestimmten Bedingung angezeigt wird. So können Sie beispielsweise ein Bildelement, ein Videoelement oder eine Schaltfläche anzeigen, wenn bestimmte Kriterien erfüllt sind. Es ist möglich, eine for-Schleife oder eine If-Bedingung in einem Block zu öffnen und in einem anderen zu schließen, was Flexibilität und Organisation bietet.

Um die Übersichtlichkeit und Trennung zu wahren, wird empfohlen, die Strukturen der Vorlagensprache in speziellen Blöcken für die Template-Sprache unterzubringen, anstatt sie mit anderen Inhalten zu vermischen. Während einfacher Text innerhalb eines Template Language-Blocks hinzugefügt werden kann, ist es am besten, separate Blöcke für komplexere Inhalte zu verwenden. Bei der Kombination von Roh-HTML mit Template-Sprachstrukturen ist es ratsam, einen Roh-HTML-Block zu verwenden, in dem der Code zusammen mit der Template-Sprache gespeichert wird, anstatt Roh-HTML in einen Template-Sprachblock aufzunehmen.

 

Funktionen

Wie bereits erwähnt, sind Funktionen ein wesentlicher Bestandteil der Template-Sprache von Mailjet und bieten eine Reihe von Vorgängen, die vom System ausgeführt werden können. Diese Funktionen ermöglichen Formatierungseffekte in verschiedenen Bereichen, wie z. B.:

• Mathematische Operationen: Runden numerischer Werte.
• String-Manipulationen: Konvertieren von Strings in Groß- oder Kleinbuchstaben oder Großschreiben des ersten Buchstabens.
• Zahlenformatierung: Zahlen basierend auf bestimmten Regeln formatieren.
• URL-Kodierung: Konvertieren einer Zeichenfolge in ein URL-sicheres Format.
• String-Escape: Sicherstellen, dass Sonderzeichen in einer Zeichenfolge ordnungsgemäß codiert werden.

Durch die Kombination dieser Funktionen mit Variablen, Wenn-Bedingungs-Anweisungen und Operatoren, die in der Mailjet-Vorlagen-Sprachreferenz erwähnt werden, können Sie hochgradig anpassbare und dynamische Inhalte erstellen.

In diesem Abschnitt untersuchen wir zwei spezifische Funktionen: die Set-Funktion und die FormatNumberLocale-Funktion.

 

Funktion einstellen

Die Set-Funktion ist eine leistungsstarke Funktion, die es uns ermöglicht, einer Variablen innerhalb der Vorlage oder des E-Mail-Inhalts direkt einen Wert zuzuweisen, sodass die Variable nicht mehr im SAPI-Aufruf oder in der SMTP-Sitzung deklariert werden muss.

Schauen wir uns ein Beispiel an: t.

Im obigen Beispiel verwenden wir die Set-Funktion, um der Variablen "testVar" innerhalb der Vorlage selbst einen Wert zuzuweisen. In der nächsten Zeile wird die gleiche Variable in einem Satz verwendet.

 

Mithilfe der Set-Funktion kann man eine Nachricht mit einem leeren Variables-Objekt wie folgt übertragen:

Mit diesem Ansatz können wir Nachrichten senden, ohne die Variable im API-Aufruf explizit zu definieren, und die Nachricht wird nicht blockiert. Hier ist das Ergebnis, wenn die Nachricht gesendet wird:

Einer der interessanten Aspekte der Set-Funktion ist, dass Sie sie innerhalb desselben Inhalts mehrfach verwenden können, um den Wert derselben Variablen zu aktualisieren. Sehen wir uns ein Beispiel an, das eine Aussage korrigiert:

Im obigen Beispiel wird der Wert der Variablen "testVar" innerhalb der Vorlage aktualisiert. Die zweite Zuweisung setzt den Anfangswert außer Kraft, was zu folgender Ausgabe führt:

Es ist wichtig zu beachten, dass, wenn Sie einen Wert für dieselbe Variable über den API-Aufruf oder die SMTP-Sitzung übergeben, dieser nicht den Wert überschreibt, der mit der Set-Funktion innerhalb der Vorlage festgelegt wurde.

 

FormatNumberLocale-Funktion

Mit der Funktion FormatNumberLocale können Sie Fließkommazahlen (Zahlen mit Dezimalbrüchen) nach bestimmten Regeln formatieren. Sie beruht auf drei Eigenschaften:

• Format: Gibt das gewünschte Format der Nummer an.
• Nummer: Gibt die Nummer an, die formatiert werden soll.
• Gebietsschema: Wählt das Gebietsschema aus, um den Dezimalpunkt und das Tausendertrennzeichen zu bestimmen.

Betrachten Sie beispielsweise den folgenden Vorlagencode:

In diesem Beispiel verwenden wir das französische Gebietsschema („fr_FR“), um die Zahl 3500 im Format "#,###.00" zu formatieren. Das Ergebnis ist dann:

Wie Sie sehen, enthält die Zahl nun Tausendertrennzeichen und Dezimalpunkte gemäß dem französischen Format.

Die Funktion FormatNumberLocale unterstützt auch andere Formatvarianten, wie z. B.:

Diese Beispiele zeigen, wie sich geringfügige Abweichungen im Format auf das Ergebnis auswirken können. Für die Formatierung wird das Gebietsschema "en_GB" verwendet. Die Ausgaben werden folgende sein:

Achten Sie bei der Verwendung dynamischer Variablen mit der Funktion FormatNumberLocale auf die korrekte Syntax:

Stellen Sie sicher, dass die Variable "var:VarName" ohne Anführungszeichen oder Klammern angegeben wird. Geben Sie außerdem den Wert für die Variable als Ganzzahl im API-Aufruf oder in der SMTP-Sitzung an:

Die Verwendung von Anführungszeichen um den Wert herum führt zu Fehlern in der Schablonensprache.

Diese Funktionen ermöglichen Ihnen zusammen mit den umfangreichen Möglichkeiten der Mailjet-Template-Sprache, hochgradig individuelle und dynamische Inhalte in Ihren E-Mails zu erstellen. 

Zusätzliche Hinweise

Es ist erwähnenswert, dass Variablen außerhalb von Textfeldern, HTML- oder Template-Sprachblöcken hinzugefügt werden können. Sie können Variablen in verschiedene andere Elemente einfügen, z. B. Hyperlinks, Schaltflächen und Bild-URLs in Image DnD-Elementen.

Wenn Sie eine Variable in einem Hyperlink oder in der URL einer Schaltfläche verwenden, können Sie einen Standardvariablenwert verwenden. Es ist jedoch wichtig zu beachten, dass Sie keine Standardvariable innerhalb der URL verwenden können, die mit einem Bild-DnD-Element verbunden ist. Das System erlaubt es Ihnen, die Variable im URL-Feld mit einem Standardwert zu speichern, aber es entfernt sie sofort

Bitte beachten Sie, dass das Hinzufügen einer Standardvariablen innerhalb des Links eines Button-Elements oder eines Hyperlinks möglich ist und problemlos funktioniert. Es kann jedoch sein, dass Sie im Editor eine Fehlermeldung erhalten, die Sie ignorieren können. Achten Sie darauf, dass der Standardwert ohne Anführungszeichen und ohne ein HTTP/HTTPS-Protokoll am Anfang hinzugefügt wird. Beispiel: {{var:Link:www.mailjet.com}}

Ein weiterer wichtiger Punkt, den es zu beachten gilt, ist die Deklaration von Variablen im SAPI-Aufruf/SMTP-Session. Sie sollten genau so aussehen, wie sie in den Inhalt der Nachricht eingefügt wurden. Die Groß- und Kleinschreibung spielt eine entscheidende Rolle, achten Sie also auf Abweichungen in der Groß- und Kleinschreibung. Wenn ein Punkt (.) in Variablen verwendet wird, weist dies auf mehrdimensionale Objekte oder Arrays hin. Wenn ein Trennzeichen benötigt wird, anstatt eine mehrdimensionale Struktur anzugeben, ist ein Unterstrich (_) eine bessere Wahl als ein Punkt.

Vorlage Aktualisierungen: strengere Syntax und Verhaltensänderungen (Oktober 2025)

Wir haben Updates eingeführt, die Zuverlässigkeit und Performance verbessern und die Syntaxvalidierung strenger machen. Wenn Ihre Templates bisher auf eine tolerante Verarbeitung angewiesen waren, überprüfen Sie bitte die folgenden Änderungen.

👉 Strengere Behandlung von Tags

{% if %} / {% for %}-Blöcke müssen jetzt zwingend korrekt geschlossen werden. Fehlende {% endif %} oder {% endfor %} führen zu einem Fehler (zuvor konnten unvollständige Blöcke teilweise toleriert werden).

{% if var:is_promo %}
  <p>Promo!</p>
{% endif %}

👉 Variablen-Namespaces: var und data

• Wenn die Variable deklariert/bekannt ist (im Schema existiert), aber nicht im Payload enthalten ist, ist die Verarbeitung nun toleranter (wird je nach Kontext als leer/false aufgelöst).
• Wenn eine Variable überhaupt nicht definiert ist, wird ein Fehler zurückgegeben.

{% if var:user.first_name %}Hello {{ var:user.first_name }}!{% endif %}

👉 Bezeichner vs. Operationen

Abstände um Operatoren herum sind wichtig. Der Parser unterscheidet zwischen Bezeichnern und Ausdrücken:

• var:x-1 → wird als einzelner Bezeichner mit dem Namen x-1 interpretiert
• var:x - 1 → wird als Subtraktion interpretiert (x minus 1)

{{ var:price - 1 }}   {# subtraction #}
{{ var:price-1 }}     {# key literally named "price-1" #}

👉 Link-Rewriting für Klick-Tracking

<a>-Tags ohne in Anführungszeichen gesetztes href wurden zuvor vom Link-Rewriter übersprungen. Sie werden jetzt umgeschrieben und getrackt.

<a href={{ var:url }}>Open</a>

<a href="{{ var:url }}">Open</a>

👉 Ersetzung des Unsubscribe-Links

[[ UNSUB_LINK ]] wird nun korrekt in allen Teilen des Nachrichtenkörpers ersetzt, einschließlich Partials/Blöcken, in denen der Platzhalter zuvor manchmal fehlte.

<p>To unsubscribe, click [[ UNSUB_LINK ]]</p>

👉 Performance-Verbesserungen

Die durchschnittliche Verarbeitungslatenz von Templates wurde verbessert, was zu schnellerer E-Mail-Personalisierung zur Sendezeit führt.

👉 Allgemeine Syntaxstrenge

Der Templater erzwingt die Syntax nun strenger. Häufige Validierungsfehler umfassen:

• Unvollständig geschlossener Block (fehlendes {% endif %} oder {% endfor %})
• Nicht definierte Variable (Verweis auf einen Schlüssel, der nicht in var/data existiert)
• Fehlerhafter Ausdruck (Operatorabstände oder nicht abgeglichene Begrenzungszeichen)

👉 Checkliste

1. Führen Sie einen Testrender für jedes Produktionstemplate durch (verwenden Sie Payloads, die optionale Felder enthalten und auslassen).
2. Schließen Sie jeden Kontrollblock mit {% endif %} / {% endfor %}.
3. Definieren Sie Ihre Variablen (Schema) oder liefern Sie sie im Payload; vermeiden Sie undefinierte Referenzen.
4. Überprüfen Sie arithmetische Ausdrücke und Bezeichner: Fügen Sie Leerzeichen um Operatoren ein, die ausgewertet werden sollen.
5. Setzen Sie Anführungszeichen um alle href-Werte: href="{{ var:url }}".
6. Prüfen Sie das Vorhandensein und Rendering von [[ UNSUB_LINK ]] überall dort, wo er erscheint.

Template-Fehler-Management

Entdecken Sie diesen umfassenden Artikel , der Sie durch den Prozess der Nutzung der Vorlagenfehlerverwaltungsfunktion von Mailjet führt. Diese leistungsstarke Funktion automatisiert die Überprüfung Ihrer Vorlagen, spart Ihnen wertvolle Zeit und macht manuelle Überprüfungen überflüssig. Verabschieden Sie sich von der mühsamen Aufgabe, jede Vorlage einzeln zu prüfen, und begrüßen Sie einen rationalisierten Ansatz für effizientes Fehlermanagement.