E-Mail-Templates

Ein Template besteht aus einer Betreffzeile und einem E-Mail-Body, die Sie einmal speichern und beliebig oft versenden. Die veränderlichen Teile schreiben Sie als {{ variable }}-Platzhalter, veröffentlichen das Template und versenden es dann per Slug, statt dasselbe HTML in jeden API-Aufruf einzufügen. Ein Template gehört zu Ihrem Workspace.

Erstellen und verwalten Sie Templates unter Email > Templates, über /v1/email/templates, mit dem bird CLI oder über den MCP server. Typisierte Methoden sind in den TypeScript-, Python-, PHP- und Go-SDKs unter email.templates verfügbar. Vollständige Request- und Response-Schemas finden Sie in der API-Referenz. Versenden Sie ein veröffentlichtes Template über den regulären Send-Endpoint.

Was ein Template enthält

Jedes Template hat zwei Namen, und sie erfüllen unterschiedliche Aufgaben:

slug ist der Name, unter dem Sie das Template versenden, zum Beispiel welcome-email. Sie wählen ihn beim Erstellen des Templates, und er kann danach nicht mehr geändert werden. Ein Slug darf Kleinbuchstaben, Ziffern, Bindestriche und Unterstriche enthalten, muss mit einem Buchstaben oder einer Ziffer beginnen und enden und darf bis zu 63 Zeichen lang sein. Zwei Präfixe sind nicht erlaubt: bird_, reserviert für unsere eingebauten Templates, und emt_, das Format für Template-IDs. Im Dashboard heißt dieses Feld Alias.
name ist ein frei wählbares Anzeigelabel. Standardmäßig entspricht es dem Slug, und Sie können es jederzeit ändern. Nichts wird über den Namen aufgelöst, daher bricht das Umbenennen eines Templates zu Anzeigezwecken keinen Versand.

Daneben hat ein Template eine permanente emt_-ID, die für seine gesamte Lebensdauer feststeht. Es hat außerdem eine category, entweder marketing oder transactional, und eine Authoring-source: html, fertiges Markup, das Sie bereitstellen und optional mit Liquid personalisieren. Die Kategorie und die Quelle werden beide beim Erstellen des Templates festgelegt.

Wir stellen einen Katalog von eingebauten Templates bereit, deren Slugs alle mit bird_ beginnen. Ein eingebautes Template gehört zu keinem Workspace, kann nicht bearbeitet werden und ist immer sofort versendbar. Kopieren Sie eines in Ihren Workspace, um es zu Ihrem zu machen – es wird dann ein gewöhnliches Template, das Sie bearbeiten können. Die Kopie kommt als unveröffentlichter Entwurf, der Kategorie, Quelle und Spracheinstellungen des Originals übernimmt. Veröffentlichen Sie es daher, bevor Sie es versenden.

Entwürfe und veröffentlichte Versionen

Jedes Template hat genau einen Entwurf (Draft), die Arbeitskopie, die Sie bearbeiten. Dazu kommt eine beliebige Anzahl veröffentlichter Versionen, jeweils nummeriert (1, 2, 3 usw.) und nach dem Erstellen unveränderlich. Bearbeiten ändert den Entwurf direkt. Veröffentlichen erstellt einen Snapshot des aktuellen Entwurfs, macht daraus die nächste nummerierte Version und setzt diese als die Version ein, die Sends verwenden. Der Entwurf selbst bleibt bearbeitbar, sodass Sie direkt an der nächsten Version weiterarbeiten können.

Die Regel, die für den Versand zählt: Ein Send verwendet immer die veröffentlichte Version des Templates, und ein Entwurf wird nie eigenständig versendet. Sie können den Entwurf weiter bearbeiten, während eine stabile Version ausgeliefert wird, und veröffentlichen, wenn die Änderung fertig ist. Das Veröffentlichen einer neuen Version ändert, was spätere Sends rendern. Ein bereits angenommener Send wird von einer späteren Veröffentlichung nicht beeinflusst.

Der Versions-Tab des Templates mit einer Draft-Zeile und veröffentlichten v3-, v2- und v1-Zeilen mit Erstellungs- und Veröffentlichungsdatum

Versionen unterstützen zwei weitere Aktionen. Entwurfsänderungen verwerfen setzt den Entwurf auf den aktuell veröffentlichten Stand zurück. Oder Rollback, um eine früher veröffentlichte Version wieder als die von Sends verwendete Version einzusetzen. Ein Rollback ist nur auf eine veröffentlichte Version möglich, nie auf den Entwurf selbst. Beim Rollback wird der Entwurf durch den Inhalt dieser Version ersetzt, sodass alles Ungespeicherte im Entwurf verloren geht und die weitere Bearbeitung bei der zurückgesetzten Version beginnt. Ein Rollback erzeugt keine neue Version.

Um ein vorhandenes Bild auszuwählen, benötigen Sie Lesezugriff auf die Medienbibliothek des Workspace. Um ein neues Bild hochzuladen, einzufügen oder per Drag-and-drop abzulegen, benötigen Sie Schreibzugriff. Wenn Bild einfügen deaktiviert ist oder Sie die Bibliothek nicht durchsuchen oder keine Bilder hochladen können, bitten Sie einen Workspace-Administrator um die entsprechende Berechtigung für die Medienbibliothek. Die Berechtigung zum Bearbeiten von Templates allein gewährt keinen Zugriff auf die Medienbibliothek.

Wählen Sie im Dashboard Visuell > Bild einfügen, um Ihre Medienbibliothek zu durchsuchen oder ein PNG-, JPEG-, GIF- oder WebP-Bild mit bis zu 5 MB hochzuladen. Statische WebP-Bilder werden in PNG oder JPEG umgewandelt. Wählen Sie das Bild aus, um seine Bildbeschreibung, Anzeigebreite, Ausrichtung und Verlinkung festzulegen. Markieren Sie es nur als Dekoratives Bild, wenn es keine Informationen vermittelt. Ein verlinktes Bild braucht eine Beschreibung, die sein Linkziel erklärt. Jede Sprache behält ihre eigenen Bildbeschreibungen und ihr Layout.

Mit Bild ersetzen tauschen Sie das ausgewählte Bild aus und behalten Beschreibung, Link, Breite und Ausrichtung bei. Sie können auch jeweils eine Bilddatei in den visuellen Editor einfügen oder ziehen. Warten Sie, bis der Upload abgeschlossen ist, oder brechen Sie ihn ab, bevor Sie speichern oder eine Testnachricht senden. Prüfen Sie die Vorschau und öffnen Sie dann Weitere Aktionen > Test-E-Mail, um sich den aktuellen Inhalt zu senden. Code bleibt zum Bearbeiten von HTML verfügbar.

Wenn Sie ein Bild aus der Medienbibliothek entfernen, bleibt es in bereits gesendeten E-Mails erhalten. Ein Ersatzbild erhält eine neue URL, sodass frühere Nachrichten weiterhin das Original anzeigen.

Speichern wird durch eine Revisionsnummer geschützt. Senden Sie die revision, die Sie zuletzt für die zu speichernde Sprache gelesen haben. Falls jemand anderes diese Sprache zwischenzeitlich geändert hat, wird das Speichern als Konflikt abgelehnt, statt die Änderung zu überschreiben. Lassen Sie revision weg, um bedingungslos zu speichern. Veröffentlichen und Rollback verwenden die revision des Entwurfs auf die gleiche Weise.

Inhalte in mehr als einer Sprache

Ein Template enthält Inhalte in bis zu 25 Sprachen, jede mit eigenem Betreff und Body, gekennzeichnet mit einem BCP-47-Code wie en oder pt-BR. Eine Sprache ist der Standard des Templates. Beim Veröffentlichen werden alle enthaltenen Sprachen gleichzeitig veröffentlicht. Sie können nicht eine einzelne Sprache veröffentlichen, daher müssen alle fertig sein. Jede Sprache braucht einen Betreff und einen Body, und die Standardsprache des Templates muss eine der ausgefüllten Sprachen sein. Fehlt etwas davon, wird nichts veröffentlicht, und der Fehler nennt pro Sprache, was fehlt, sodass Sie alles in einem Durchgang beheben können. Sie müssen nicht alle Sprachen von Anfang an fertigstellen: Veröffentlichen Sie die fertigen, und fügen Sie den Rest später hinzu.

Eine Sprache braucht einen HTML-Body. Sie können text weglassen: Beim Veröffentlichen wird dann automatisch eine Nur-Text-Alternative aus dem HTML erzeugt, sodass Sie beide Teile erhalten, ohne den zweiten selbst schreiben zu müssen.

Jede Sprache kann außerdem einen Vorschautext (Preview-Text) enthalten, manchmal auch Preheader genannt: die Zeile, die ein Posteingang nach dem Betreff in der Nachrichtenliste anzeigt. Er ist optional, bis zu 255 Zeichen lang und akzeptiert dieselben {{ variable }}-Platzhalter wie der Betreff. Lassen Sie ihn weg, greift der Posteingang stattdessen auf die erste Zeile des Bodys zurück – selten die Zeile, die Sie wählen würden. Beim Veröffentlichen wird Vorschautext abgelehnt, wenn der Body der Sprache keinen HTML-Teil hat, da ein Mail-Client die Vorschauzeile nur aus verstecktem HTML-Markup liest. Ebenso wird {{ bird.unsubscribe_url }} darin abgelehnt, aus demselben Grund, warum der Betreff es nicht enthalten kann: Beides ist kein Ort für einen Link.

Zwei Einstellungen regeln einen Send, der keine Sprache nennt, für die das Template Inhalte hat, und sie schützen vor unterschiedlichen Fehlern:

Einstellung	Was sie steuert
on_missing_language	Was passiert, wenn ein Send eine Sprache anfragt, die das Template nicht hat. fallback, der Standard, liefert die nächstliegende Übereinstimmung. Zuerst wird eine allgemeinere Form derselben Sprache versucht, sodass ein gespeichertes pt eine Anfrage für pt-BR bedienen kann. Dann wird auf die Standardsprache des Templates zurückgegriffen. fail lehnt den Send stattdessen ab, für Inhalte, bei denen der Versand in der falschen Sprache schlimmer ist als gar kein Versand.
language_source_required	Ob ein Versand überhaupt eine Sprache angeben muss. Standardmäßig ist diese Einstellung deaktiviert, sodass ein Versand ohne Sprachangabe die Standardsprache erhält. Aktivieren Sie sie, und dieser Versand wird stattdessen abgelehnt. Ein Broadcast benennt eine Sprache für sein gesamtes Publikum, daher muss bei einem Template mit dieser Einstellung die Sprache gewählt sein, bevor der Broadcast senden kann.

Einstellung

Was sie steuert

on_missing_language

Was passiert, wenn ein Send eine Sprache anfragt, die das Template nicht hat. fallback, der Standard, liefert die nächstliegende Übereinstimmung. Zuerst wird eine allgemeinere Form derselben Sprache versucht, sodass ein gespeichertes pt eine Anfrage für pt-BR bedienen kann. Dann wird auf die Standardsprache des Templates zurückgegriffen. fail lehnt den Send stattdessen ab, für Inhalte, bei denen der Versand in der falschen Sprache schlimmer ist als gar kein Versand.

language_source_required

Ob ein Versand überhaupt eine Sprache angeben muss. Standardmäßig ist diese Einstellung deaktiviert, sodass ein Versand ohne Sprachangabe die Standardsprache erhält. Aktivieren Sie sie, und dieser Versand wird stattdessen abgelehnt. Ein Broadcast benennt eine Sprache für sein gesamtes Publikum, daher muss bei einem Template mit dieser Einstellung die Sprache gewählt sein, bevor der Broadcast senden kann.

Sie können diese beiden Einstellungen unabhängig voneinander setzen. Allein angewendet greift fail nur, wenn ein Send eine Sprache nennt, die wir nicht haben – ein Send ohne Sprachangabe kommt trotzdem durch. Aktivieren Sie beide Einstellungen zusammen, wenn jeder Send bewusst eine Sprache angeben soll.

Personalisierung mit Variablen

Schreiben Sie {{ variable }}-Platzhalter in Betreff, Vorschautext und Body. Wir erkennen sie automatisch, sprachübergreifend zusammengefasst, sodass Sie sie nie separat deklarieren müssen. Das Platzhalter-Präfix unterscheidet die zwei Arten. Ein Pfad, der mit bird. beginnt, liest aus unseren Daten, entweder einem Kontaktdatensatz oder dem Abmelde-Link. Alles andere ist ein Parameter, dem Sie beim Versand einen Wert geben.

Der Name eines Parameters ist ein einzelnes Wort, wie {{ animal }}. Ein punktierter Name greift auf eine Struktur zu, die ein Parameter nicht hat, daher wird das Veröffentlichen abgelehnt: Schreiben Sie den Wert als eigenen Parameter, oder lesen Sie Kontaktdaten mit bird.contact.<attribute>.

Bei einem Einzelversand oder Batch kommt der Wert eines Parameters aus dem template.parameters-Objekt des Sends, zugeordnet über seinen Namen. Ein Satz von Werten gilt für alle Empfänger dieses Sends. bird ist der einzige Name, den Sie dort nicht verwenden können: Ein template.parameters-Schlüssel namens bird wird mit einem 422 abgelehnt.

Ein Broadcast hat kein parameters-Objekt, daher kann sein Inhalt nur bird.-Platzhalter verwenden. bird.contact.<attribute> wird aus den eigenen Kontakteigenschaften jedes Empfängers gefüllt, was den Inhalt pro Empfänger personalisiert. Jede Kontakteigenschaft ist über ihren eigenen Schlüssel verfügbar, ebenso die drei eingebauten Felder: first_name, last_name und email.

Codebeispiel

Hi {{ bird.contact.first_name }},

Jeder Parameter im Template benötigt beim Versand einen Wert. Andernfalls gibt API einen 422 zurück, der den fehlenden Parameter benennt. Geben Sie Werte für Parameter über alle Sprachen hinweg an, da die gewählte Sprache von den Fallback-Einstellungen abhängen kann. Eine fehlende Kontakteigenschaft wird als leerer Wert gerendert – fügen Sie daher für kundenrelevanten Inhalt einen Fallback hinzu: {{ bird.contact.first_name | default: "there" }}.

Ein Broadcast ist strenger bei den Namen, die er akzeptiert, weil Kontakteigenschaften das Einzige sind, womit er Platzhalter füllen kann. Seine bird.contact.*-Platzhalter dürfen nur ein eingebautes Feld oder eine im Workspace registrierte Kontakteigenschaft benennen. Jeder andere Platzhalter, einschließlich eines Parameters, kann vom Broadcast nicht gefüllt werden. Der Versand wird abgelehnt, und der Fehler benennt den Platzhalter.

Was das Archivieren einer Eigenschaft für ein Template ändert, betrifft nur neuen Inhalt: Die Eigenschaft verschwindet aus der Auswahl im Editor, und das Veröffentlichen einer Version, deren Inhalt sie liest, wird unter Nennung der Eigenschaft abgelehnt. Vor der Archivierung veröffentlichte Versionen sind nicht betroffen.

Platzhalter verwenden Liquid, sodass Filter und Kontrollfluss neben einfacher Ersetzung funktionieren. Ein {% if %}-Bedingungsblock und eine {% for %}-Schleife über einen Array-Wert sind beide zulässig. Eine Handvoll Konstrukte wird beim Veröffentlichen abgelehnt, und der Fehler benennt genau, was zu ändern ist:

Partielle Includes mit {% include %} oder {% render %}.
Die Tags increment, decrement und ifchanged.
Die Filter money, format_date, format_time, json, inspect und type.
Vergleiche mit empty oder blank. Verwenden Sie stattdessen .size == 0.
Blöcke, die weit tiefer verschachtelt sind, als reales E-Mail-Markup erfordert.

Das Template eines Broadcasts darf überhaupt keine {% for %}-Schleife verwenden, weil ein Broadcast pro Kontakteigenschaft nur einen Wert einsetzt und nichts zum Iterieren hat. Wenn Ihr Inhalt eine Schleife braucht, senden Sie ihn stattdessen über den Messages-API.

Jedes Template verwendet Liquid, auch eines, das nur {{ variable }}-Platzhalter enthält. Vor dem Veröffentlichen validieren wir Betreff, Vorschautext, HTML und Nur-Text-Inhalt als Liquid. Wir fügen außerdem den Filter escape zu jeder HTML-Ausgabe hinzu, die nicht bereits mit escape oder escape_once endet, damit ein Wert mit & oder < das umgebende Markup nicht verändern kann. Die reservierte Abmelde-Ausgabe bleibt unverändert, damit der Versand sie ersetzen kann. Die Betreffzeile und der Nur-Text-Body bleiben wie geschrieben. Weil das Veröffentlichen diese Filter hinzufügt, ist das HTML, das Sie aus einer veröffentlichten Version lesen, möglicherweise nicht byteidentisch mit dem, was Sie eingereicht haben.

Setzen Sie eine vollständige URL direkt in ein href, zum Beispiel <a href="{{ sign_in_url }}">Sign in</a>. Fügen Sie url_encode nicht auf den gesamten Wert an. Es prozent-codiert https://, /, ? und &, wodurch das Ergebnis nicht mehr als absoluter Link funktioniert. Wir fügen HTML-Escaping hinzu und bewahren dabei die URL-Struktur. Wenn ein Parameter nur eine URL-Komponente liefert, codieren Sie diese Komponente explizit: <a href="https://example.com/search?q={{ query | url_encode }}">Search</a>.

Vorschau vor dem Veröffentlichen

Rendern Sie ein Template mit Beispielwerten und erhalten Sie die Betreffzeile sowie den HTML- und Nur-Text-Body zurück, die ein Versand ausliefern würde. Die Vorschau verwendet unseren lokalen Liquid-Renderer und rendert standardmäßig den Entwurf – so prüfen Sie eine Änderung, bevor sie live geht. Sie kann auch eine veröffentlichte Version rendern. Sie funktioniert für Ihre eigenen Templates und für unsere eingebauten, und es wird nichts gesendet.

Sie können auch den Inhalt selbst übergeben, anstatt den Entwurf lesen zu lassen. Übergeben Sie einen Betreff und Bodies, und diese werden gerendert, genau wie ein Entwurf behandelt – so kann ein Editor eine Änderung beim Tippen anzeigen, ohne vorher etwas zu speichern.

Die Personalisierung wird für Sie ausgefüllt, sodass das Ergebnis als fertiger Text erscheint, nicht als {{ }}-Platzhalter. Geben Sie einen contact an, und jeder bird.contact.<attribute> wird gegen die Eigenschaften dieses Kontakts aufgelöst – so prüfen Sie Ihre Formulierungen an einem echten Datensatz, bevor ihn jemand erhält. Die Werte stammen aus derselben Projektion, die ein Broadcast zum Füllen seiner Platzhalter verwendet, sodass die Vorschau dasselbe Ergebnis liefert wie ein Versand.

Lassen Sie contact weg, und stattdessen werden Platzhalterwerte eingesetzt: Bird und Test für Vor- und Nachname, bird.test@example.com für die E-Mail-Adresse und für jede weitere Eigenschaft deren registrierter Fallback. Eine referenzierte Eigenschaft ohne Fallback wird als Schlüssel in Klammern gerendert, zum Beispiel [loyalty_tier] – das zeigt Ihnen sowohl, dass der Wert ein Platzhalter ist, als auch, welche Eigenschaft noch einen Fallback braucht.

Ein Kontakt wird so gelesen, wie er gerade ist. Das macht die Vorschau zum richtigen Werkzeug, um Inhalt zu prüfen, den Sie gleich senden, und zum falschen, um zu fragen, was ein früherer Versand enthielt. Um zu lesen, was ein Versand tatsächlich ausgeliefert hat, öffnen Sie die Nachricht stattdessen im E-Mail-Log – dort wird sie mit den Werten gerendert, die dieser Versand mitführte.

Fügen Sie language hinzu, um eine bestimmte Sprache zu rendern, oder lassen Sie es weg für die Standardsprache des Templates. Die Antwort teilt Ihnen mit, welche Sprache gerendert wurde – das ist wichtig, wenn die angeforderte Sprache nicht vorhanden ist und die on_missing_language-Einstellung des Templates eine ähnliche Sprache geliefert hat.

Wenn der Entwurf Personalisierung enthält, die beim Veröffentlichen abgelehnt würde, gibt die Vorschau denselben Fehler zurück – so dient sie auch als Möglichkeit, Probleme frühzeitig zu finden.

Im Template-Builder des Dashboards zeigt Preview with contact data am unteren Rand der linken Leiste die gerenderte E-Mail neben dem, was Sie gerade bearbeiten, sowohl im visuellen als auch im Code-Editor. Die Auswahl darunter bestimmt, wessen Daten die Platzhalter füllen, und Sample data sind die oben genannten Platzhalterwerte.

Senden mit einem Template

Setzen Sie das template-Feld des Versands auf ein Objekt, das das Template benennt, entweder per id (emt_...) oder per slug – verwenden Sie genau eines der beiden. Geben Sie die Variablenwerte in template.parameters an. Fügen Sie language hinzu, um eine bestimmte Sprache auszuwählen, oder lassen Sie es weg, um die Standardsprache des Templates zu senden, es sei denn, das Template verlangt bei jedem Versand eine Sprachauswahl. Lassen Sie subject, html und text komplett weg, weil das Template sie bereits liefert.

Codebeispiel

{
  "from": "hello@yourdomain.com",
  "to": ["delivered@messagebird.dev"],
  "category": "transactional",
  "template": {
    "slug": "welcome-email",
    "parameters": { "first_name": "Jane" }
  }
}

Ein Verhalten, das Sie einplanen sollten: Die Kategorie des Templates ist ein Standardwert, und das category des Versands überschreibt ihn. Lassen Sie category weg, und der Versand erbt die Kategorie des Templates, sodass ein operatives Template als transaktional versendet wird, ohne dass Sie es bei jedem Aufruf wiederholen. Setzen Sie category, und Ihr Wert hat Vorrang. Den Rest des versandseitigen Vertrags finden Sie unter Senden mit einem Template.

Erstellung außerhalb des Dashboards

Der gesamte Lebenszyklus ist auch außerhalb des Dashboards verfügbar. Der Veröffentlichungsschritt heißt dort submit, und er ist die Operation, die den Entwurf in die nächste veröffentlichte Version umwandelt:

Codebeispiel

bird email templates create welcome-email --category marketing --source html
bird email templates versions languages set <emt_...> <emv_...> en --subject "Hi {{ bird.contact.first_name }}" --html "<p>Hello</p>"
bird email templates versions submit <emt_...> <emv_...> --validate-only   # report problems, freeze nothing
bird email templates versions submit <emt_...> <emv_...>                   # freeze, go live

create gibt das Template zusammen mit seiner draft_version_id zurück, die jeder Versions- und Sprachbefehl benötigt. --validate-only führt dieselben Vollständigkeitsprüfungen wie ein echtes Submit durch, ohne etwas einzufrieren – das ist der günstige Weg, alle Probleme über alle Sprachen hinweg in einem Durchgang zu finden. Beim Zurücklesen eines Templates erhalten Sie seine Metadaten und seinen Pro-Sprache-Status, aber keinen Inhalt. Inhalt liegt auf den Sprachen einer Version, jeweils eine Sprache.

Die SDKs bieten denselben Lebenszyklus als typisierte Methoden unter email.templates, wobei die Versions- und Sprachoperationen darunter als email.templates.versions und email.templates.versions.languages verschachtelt sind. Ein Agent erreicht dieselben Operationen über die email_templates_*-MCP-Tools.

Nächste Schritte

E-Mail senden: das vollständige Versand-Payload und wie Template-Versendungen hineinpassen
Kategorien: marketing vs. transactional pro Versand wählen
bird email templates: Templates über das Terminal verwalten
API-Referenz: vollständige Request- und Response-Schemas für alle achtzehn Template-Operationen
SDKs: die typisierten email.templates-Methoden in TypeScript, Python, PHP und Go
MCP-Server: einem Agenten das Erstellen und Veröffentlichen von Templates ermöglichen
So erstellen Sie ein E-Mail-Template: ein Video, das eines im Dashboard erstellt und dann einen Agenten ein weiteres erstellen lässt

Verwandte Ressourcen