Referenz
Template-Sprache Temple
Temple setzt beim Senden Variablen, Standardwerte und Bedingungen in Betreff, HTML und Text von E-Mails ein. Syntax, Wahrheitswerte, Escaping und wo Temple ausgeführt wird.
Temple ist die kleine Template-Sprache von Emailit für Betreffzeilen, HTML und Nur-Text. Sie ist weder Liquid noch Handlebars: Sie unterstützt Variablen, verschachtelte Pfade, Standardwerte und if/else-Blöcke, sonst nichts. Vorlagen speichern Platzhalter so, wie Sie sie schreiben, und Temple füllt sie aus, wenn eine E-Mail per API, über eine Automatisierung oder als Kampagne gesendet wird.
Syntax auf einen Blick
{{first_name}} Variable
{{user.name}} {{items.0.sku}} Nested property and list item
{{first_name|"there"}} Default when the value is missing or null
{{#if plan}} … {{else}} … {{/if}} Conditional, with an optional elseTemple hat keine Schleifen, Filter, Helper, Partials oder eigenen Funktionen. Der einzige Operator ist der Standardwert |.
Variablen
Hello {{first_name}}- Temple ersetzt
{{first_name}}durch den Wertfirst_name, den Sie übergeben. Leerzeichen innerhalb der geschweiften Klammern werden ignoriert,{{ first_name }}funktioniert also auch. - Namen unterscheiden Groß- und Kleinschreibung:
{{First_Name}}passt nicht zufirst_name. - Ein fehlender Wert oder
nullwird zu einem leeren String. Unbekannte Platzhalter verschwinden, statt in der E-Mail aufzutauchen. - Werte werden in Text umgewandelt. Zahlen und Booleans erscheinen so, wie sie geschrieben sind (
42,true), und Listen werden mit Kommas verbunden (aus["a","b"]wirda,b). Ein Objekt wird als[object Object]ausgegeben. Verweisen Sie daher auf eines seiner Felder.
Verschachtelte Eigenschaften und Listeneinträge
Verwenden Sie Punkte, um in Objekte zu gelangen, und Zahlen für Listenpositionen, beginnend bei 0:
{{user.name}}
{{order.items.0.sku}}{
"user": { "name": "Ada" },
"order": { "items": [{ "sku": "A1" }, { "sku": "B7" }] }
}Da der Punkt die Pfadsegmente trennt, lässt sich ein Schlüssel, der selbst einen Punkt enthält, nicht erreichen. Verwenden Sie Schlüssel ohne Punkte.
Standardwerte
Fügen Sie | und einen Ersatzwert hinzu, der verwendet wird, wenn der Wert fehlt oder null ist:
Hi {{first_name|"there"}},
Your company: {{company|'Not set'}}Doppelte Anführungszeichen, einfache Anführungszeichen oder gar keine funktionieren gleichermaßen. Der Standardwert wird nicht für einen leeren String, 0 oder false verwendet; diese werden als leer, 0 und false ausgegeben. Ein Standardwert darf das Zeichen } nicht enthalten.
Bedingungen
{{#if plan}}
Thanks for being on the {{plan}} plan.
{{else}}
You're on the free plan. Upgrade anytime from your dashboard.
{{/if}}{{else}}ist optional.- Eine Bedingung ist falsch, wenn der Wert fehlt,
null,false,0, ein leerer String""oder eine leere Liste[]ist. Alles andere ist wahr, auch der String"0", der String"false"und ein leeres Objekt. - Eine Bedingung ist ein einzelner Variablenpfad, etwa
planoderuser.is_admin. Es gibt kein==,and,or,notoderunless. Um anhand eines Werts zu verzweigen, berechnen Sie in Ihrem Code einen Boolean und übergeben ihn, zum Beispiel"is_pro": true. - Schreiben Sie
{{else}}und{{/if}}genau wie gezeigt, ohne Leerzeichen innerhalb der geschweiften Klammern. - Temple verarbeitet zuerst die Bedingungen, dann die Variablen.
Blöcke lassen sich verschachteln. Temple löst zuerst die innersten Blöcke auf, sodass jedes {{else}} und {{/if}} zu seinem eigenen {{#if}} gehört:
{{#if plan}}
{{#if annual}}Billed yearly.{{else}}Billed monthly.{{/if}}
{{else}}
You're on the free plan.
{{/if}}Verschachtelungen funktionieren bis zu einer Tiefe von 10 Ebenen.
Escaping und Sonderzeichen
Werte werden nicht HTML-escaped. Temple fügt Werte genau so ein, wie Sie sie übergeben. Ein Wert wie Tom & Jerry oder <b>Ada</b> landet unverändert im HTML. Escapen Sie daher von Nutzern stammenden Text in Ihrem Code, bevor Sie ihn übergeben. Dieselben Variablen füllen Betreff, HTML und Text, ein escapeter Wert wie Tom & Jerry erscheint also auch so in Betreff und Text. Wenn das wichtig ist, übergeben Sie für das HTML eine separate, escapete Variable.
Das bedeutet auch, dass Sie fertiges HTML, etwa eine von Ihrem Code gerenderte Tabelle mit Bestellpositionen, als einzelne Variable übergeben können.
Für doppelte geschweifte Klammern gibt es keine Escape-Syntax. Temple behandelt alles zwischen {{ und }} als Platzhalter und entfernt es, wenn kein Wert vorhanden ist. Einfache geschweifte Klammern, etwa in CSS, sind nicht betroffen. Werte werden einmal eingefügt und nicht erneut ausgewertet. Um doppelte geschweifte Klammern wörtlich anzuzeigen, legen Sie sie daher in eine Variable:
{
"html": "<p>Write {{example}} in your template to show the first name.</p>",
"variables": { "example": "{{first_name}}" }
}Wo Temple ausgeführt wird
| Wo | Wird Temple ausgeführt? | Was Sie verwenden können |
|---|---|---|
E-Mail-API mit template |
Immer | Die übergebenen variables und global |
E-Mail-API mit subject, html oder text direkt in der Anfrage |
Wenn variables mindestens einen Schlüssel hat oder der Inhalt {{global.…}} verwendet |
Die übergebenen variables und global |
| Automatisierungen, Schritt Send email | Bei jedem Versand | Kontaktfelder, tags, score, contact, global, unsubscribe_url, manage_subscriptions_url, payload, meta, run, automation und step, sowie email in Email-Automatisierungen. Siehe E-Mails aus Automatisierungen. |
| Kampagnen, Testversände und Preview as contact | Immer | Kontaktfelder, cf, custom_fields, tags, score, global, unsubscribe_url, manage_subscriptions_url, webview_url und contact. Siehe Kampagnen. |
| SMTP-Relay | Nein | Nichts. Die Nachricht wird so gesendet, wie Sie sie erstellt haben. |
| Editoren in der Weboberfläche und ihre Vorschauen | Nein | Editoren fügen Platzhalter ein, und ihre Vorschauen zeigen sie ungerendert. Die MJML-Editoren (Alpha) zeigen Temple in der Vorschau außerdem mit Beispieldaten an. Um eine Kampagne für einen einzelnen Kontakt gerendert zu sehen, verwenden Sie Preview as contact. |
E-Mails per API
Übergeben Sie einen Vorlagen-Alias oder eine tem_-ID und ein Objekt variables. Felder, die Sie in der Anfrage senden (subject, html, text), ersetzen die der Vorlage, dann rendert Temple Betreff, HTML und Text.
{
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"template": "welcome-email",
"variables": {
"first_name": "Ada",
"plan": "Pro",
"activation_url": "https://acme.com/activate?token=8f3k2",
"cf": { "company": "Analytical Engines Ltd" }
}
}Die Editoren in der Weboberfläche fügen für eigene Felder von Kontakten {{cf.<key>}} ein. Bei Versänden per API wird nichts aus Ihren Kontakten nachgeschlagen. Übergeben Sie diese Werte daher selbst unter cf, wie im Beispiel. Dasselbe gilt für {{unsubscribe_url}}: Übergeben Sie Ihren eigenen Abmeldelink, wenn die Vorlage ihn verwendet. Globale Werte sind die Ausnahme: {{global.<key>}} wird aus dem Workspace befüllt, sofern Ihre variables keinen eigenen Schlüssel global haben.
Sie können auch Inhalte direkt in der Anfrage mit variables und ohne Vorlage senden. Siehe E-Mail senden.
E-Mails aus Automatisierungen
Bei jedem Versand rendert der Schritt Send email Betreff, HTML und Text mit Temple, ob sie aus der Vorlage oder aus Überschreibungen im Schritt stammen.
Automatisierungen mit Kontakten legen die Felder des Kontakts auf die oberste Ebene, daher funktionieren:
{{email}},{{first_name}}und{{last_name}}{{cf.<key>}}oder{{custom_fields.<key>}}für eigene Felder, zum Beispiel{{cf.plan}}.{{cf.<key>}}ist die Form, die Kampagnen und die Editoren verwenden.{{tags}}, die Tags des Kontakts alsvip, customer, und{{#if tags}}…{{/if}};{{score}}, der Lead-Score{{unsubscribe_url}}, der Abmeldelink des Kontakts, der in Marketing-E-Mails außerdem alsList-Unsubscribe-Header für die Abmeldung mit einem Klick gesendet wird, und{{manage_subscriptions_url}}, seine Seite zur Abonnementverwaltung{{contact.*}}, derselbe Kontakt als Objekt, zum Beispiel{{contact.first_name}}
Alle Automatisierungen erhalten außerdem {{global.*}}, die globalen Werte des Workspace, {{payload.*}}, die Daten des Events, das den Durchlauf ausgelöst hat, und {{meta.*}}, die Metadaten des Durchlaufs. Sie erhalten auch {{run.id}}, {{automation.id}}, {{automation.name}} und {{step.key}}, den Schlüssel des Schritts Send email. Automatisierungen mit dem Kontext Email ergänzen {{email.*}}, die E-Mail, die den Durchlauf gestartet hat, etwa {{email.mail_from}}. Automatisierungen mit dem Kontext Email oder Event haben keinen Kontakt auf oberster Ebene. Verwenden Sie dort {{payload.*}} oder legen Sie Empfänger und Betreff im Schritt fest.
Kampagnen
Kampagnen rendern Betreff, HTML und Text für jeden Empfänger mit Temple, unabhängig davon, mit welchem Editor sie erstellt wurden. Testversände und Preview as contact rendern genauso. Die Variablen stammen aus dem Kontakt des Empfängers:
{{first_name}},{{last_name}}und{{email}}{{unsubscribe_url}}, der Abmeldelink des Empfängers, und{{manage_subscriptions_url}}, seine Seite zur Abonnementverwaltung{{cf.<key>}}oder{{custom_fields.<key>}}für eigene Felder, zum Beispiel{{cf.plan}}{{tags}}, die Tags des Kontakts alsvip, customer, und{{score}}, der Lead-Score{{global.<key>}}, ein globaler Wert, zum Beispiel{{global.offer_url}}{{contact.*}}, dieselben Felder als Objekt, zum Beispiel{{contact.first_name}}
Leere Kontaktfelder gelten als fehlend, daher greifen Standardwerte: {{first_name|"there"}} ergibt there bei einem Kontakt ohne Vornamen. Testversände an eine Adresse, die zu einem Kontakt im Workspace gehört, verwenden die Daten dieses Kontakts. Bei anderen Adressen wird {{email}} mit der Testadresse gefüllt, und Namen und eigene Felder bleiben leer.
Kampagnen-Platzhalter, die vor der Umstellung der Kampagnen auf Temple geschrieben wurden, funktionieren weiterhin. Die Namen first_name, last_name, email und unsubscribe_url sowie das Präfix cf. passen unabhängig von der Groß-/Kleinschreibung, daher funktioniert {{FIRST_NAME}} nach wie vor. Die Schlüssel eigener Felder müssen genau übereinstimmen. Siehe Platzhalter in Kampagnen.
SMTP
Das SMTP-Relay nimmt eine fertige Nachricht an. Es gibt weder eine Vorlagensuche noch einen Durchlauf durch Temple. Erstellen Sie das endgültige HTML daher vor dem Senden, oder nutzen Sie die API oder eine Automatisierung, wenn Sie Variablen brauchen.
Vorlagen vor dem Veröffentlichen prüfen
Emailit lehnt eine Vorlage oder einen Versand nicht wegen fehlerhafter Temple-Syntax ab. Fehler zeigen sich meist als fehlender Text oder übrig gebliebene geschweifte Klammern in der zugestellten E-Mail. MJML-Vorlagen (Alpha) bilden die Ausnahme: Beim Speichern prüft Emailit ihr Temple und lehnt unausgeglichene Blöcke ab. Vor dem Veröffentlichen:
- Prüfen Sie, ob jedes
{{#if …}}ein passendes{{/if}}hat und jedes{{ein schließendes}}. - Senden Sie die Entwurfsversion über ihre
tem_-ID mit realistischenvariablesan sich selbst, auch mit fehlenden und leeren Werten, um beide Seiten jeder Bedingung zu sehen. Siehe Vorlagenversionen. - Verwenden Sie bei einer Kampagne Preview as contact mit Kontakten mit und ohne den jeweiligen Wert und senden Sie dann einen Test. Siehe Testen und planen.
Beispiele
Eine Begrüßung mit Ersatzwert:
Hi {{first_name|"there"}},Ein Block, der vom Tarif abhängt:
{{#if plan}}
Your plan: {{plan}}
{{else}}
Upgrade anytime from your dashboard.
{{/if}}Ein Betreff mit einem verschachtelten Wert:
Order {{order.number}} has shipped, {{user.first_name|"friend"}}