MJML-Editoren und API

MJML ist eine Auszeichnungssprache für responsive E-Mails. Sie schreiben Abschnitte, Spalten und Komponenten wie <mj-text> und <mj-button>, und MJML kompiliert sie zu HTML, das in allen E-Mail-Clients einheitlich dargestellt wird. In Emailit kann MJML die Quelle einer Vorlage oder Kampagne sein: Sie schreiben es in den Editoren der Weboberfläche oder senden es per API, und Emailit validiert es und kompiliert das HTML.

Übersicht

• Vorlagen: editor: "mjml" mit dem MJML in source. Siehe Vorlage erstellen.
• Kampagnen: content_type: "mjml" mit dem MJML in content. Siehe Kampagnen.
• Automatisierungen: Der Schritt Send email sendet eine MJML-Vorlage wie jede andere Vorlage. Siehe Automatisierungen.
• MJML-Endpunkte: MJML validieren, MJML rendern und MJML-Referenz abrufen.

Wer MJML nutzen kann

Während der Alpha steht MJML nur den Plattform-Admins von Emailit zur Verfügung. Die Rolle Admin in einem Workspace reicht nicht aus.

Alle können MJML-Vorlagen und -Kampagnen weiterhin umbenennen, veröffentlichen, exportieren, senden und löschen. Das Duplizieren einer MJML-Vorlage erstellt eine neue MJML-Vorlage und erfordert daher MJML-Zugriff.

MJML-Version

Emailit kompiliert jedes MJML mit MJML 5.4.1, sowohl auf dem Server als auch in der Live-Vorschau der Editoren. Die Validierung prüft Tags, Attribute und Attributwerte gegen diese Version. MJML-Referenz abrufen gibt die Version und alle Komponenten und Attribute zurück, die sie unterstützt.

Editoren

Die Weboberfläche hat zwei MJML-Editoren. Beide sind versioniert und befinden sich als Version 0.x in der Alpha.

Beide Editoren speichern eine Vorlage mit editor: "mjml". Das gespeicherte Dokument hält fest, welcher Editor es zuletzt gespeichert hat und in welcher Version. Teammitglieder können dieselbe Vorlage oder Kampagne gleichzeitig bearbeiten. Siehe Gemeinsam bearbeiten.

Quellformate

Überall, wo Emailit MJML annimmt (das Feld source einer Vorlage, das Feld content einer Kampagne und das Feld source der MJML-Endpunkte), können Sie jedes dieser Formate senden:

Alles andere wird mit document.unrecognized abgelehnt. Quellen über 2 MB werden mit document.too-large abgelehnt.

Das gespeicherte Dokument

Emailit speichert MJML in einer versionierten Hülle. Sie ist das source der Vorlage und der content der Kampagne:

{
  "kind": "emailit/mjml",
  "schema_version": 1,
  "mjml_version": "5.4.1",
  "editor": "api",
  "editor_version": null,
  "format": "markup",
  "content": "<mjml>\n  <mj-body>\n    …\n  </mj-body>\n</mjml>"
}

Was Sie senden, bestimmt das Format: Markup wird als markup gespeichert, MJML-JSON als json. Beides wird mit editor: "api" erfasst. Eine Hülle, die Sie senden, behält ihren editor und ihre editor_version.

API-Antworten geben source als diese Hülle zurück, serialisiert als JSON-String, und Sie können sie unverändert zurücksenden. Antworten enthalten außerdem ein Objekt mjml mit den Versionen der Hülle:

"mjml": {
  "mjml_version": "5.4.1",
  "schema_version": 1,
  "editor": "api",
  "editor_version": null,
  "format": "markup"
}

Die Weboberfläche öffnet ein Dokument in dem Editor, der es zuletzt gespeichert hat. Per API geschriebene Dokumente öffnen sich im Code Editor, wenn format den Wert markup hat, und im Visual Editor, wenn es json ist.

Kompilieren und speichern

Bei MJML-Vorlagen und -Kampagnen ist Emailit für das HTML zuständig:

• Beim Erstellen und Aktualisieren validiert Emailit das MJML und kompiliert es. Das kompilierte HTML wird als html der Vorlage gespeichert, und ein übergebenes html wird ignoriert.
• Der Versand verwendet das gespeicherte HTML. Temple-Tags bleiben darin erhalten und werden beim Senden für jeden Empfänger gerendert.
• Wenn Sie nur andere Felder aktualisieren, etwa name oder subject, wird nicht neu kompiliert.
• text wird nicht aus dem MJML erzeugt. Senden Sie text selbst, wenn Sie einen Nur-Text-Teil möchten.
• Wenn Sie eine bestehende Vorlage ohne source auf editor: "mjml" umstellen, wird das gespeicherte source der Vorlage kompiliert, das dann MJML sein muss.

Das HTML wird beim Speichern kompiliert. Das HTML einer bestehenden Vorlage ändert sich also erst, wenn sie erneut gespeichert wird.

curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "alias": "welcome",
    "subject": "Welcome, {{first_name|\"there\"}}",
    "editor": "mjml",
    "source": "<mjml><mj-head><mj-title>Welcome</mj-title><mj-preview>Your account is ready</mj-preview></mj-head><mj-body><mj-section><mj-column><mj-text>Hi {{first_name|\"there\"}}, welcome aboard.</mj-text><mj-button href=\"{{activation_url}}\">Activate account</mj-button></mj-column></mj-section></mj-body></mjml>"
  }'

Senden Sie sie dann wie jede andere Vorlage mit E-Mail senden: "template": "welcome" und ein Objekt variables.

Validierung

Jedes Speichern führt dieselben Prüfungen aus wie MJML validieren:

• XML-Syntax: nicht geschlossene oder nicht zusammenpassende Tags und fehlerhafte Attribute (xml.*)
• MJML-Struktur, Attribute und Attributwerte für MJML 5.4.1 (mjml.*)
• Temple-Syntax und ausgeglichene {{#if}}-Blöcke (temple.*)
• Das Quellformat und die Versionen (document.*) sowie der Compiler selbst (compiler.*)

Jeder Befund ist eine Diagnose mit einem Schweregrad:

Eine Diagnose hat diese Felder. Felder, die nicht zutreffen, werden weggelassen.

Fehlerantwort

Wird eine Vorlage oder Kampagne mit Fehlerdiagnosen gespeichert, lautet die Antwort 422. Für diese Quelle:

<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text colour="#333333">Hi {{first_name|"there"}}</mj-text>
        <mj-button href="{{cta_url}}">{{#if trial}}Start trial</mj-button>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

lautet die Antwort:

{
  "message": "The MJML is not valid.",
  "errors": {
    "source": [
      "Line 5: <mj-text> has no attribute colour. Did you mean color?",
      "Line 6: {{#if trial}} is never closed with {{/if}}."
    ]
  },
  "diagnostics": [
    {
      "severity": "error",
      "code": "mjml.unknown-attribute",
      "message": "<mj-text> has no attribute colour. Did you mean color?",
      "line": 5,
      "column": 18,
      "tag": "mj-text",
      "attribute": "colour",
      "path": [0, 0, 0, 0]
    },
    {
      "severity": "warning",
      "code": "mjml.missing-title",
      "message": "Add an <mj-title> to <mj-head>; clients and screen readers use it.",
      "line": 1,
      "column": 2,
      "tag": "mjml",
      "path": []
    },
    {
      "severity": "info",
      "code": "mjml.missing-preview",
      "message": "Add an <mj-preview> to control the inbox preview text.",
      "line": 1,
      "column": 2,
      "tag": "mjml",
      "path": []
    },
    {
      "severity": "error",
      "code": "temple.unclosed-if",
      "message": "{{#if trial}} is never closed with {{/if}}.",
      "line": 6,
      "column": 39,
      "tag": "mj-button",
      "path": [0, 0, 0, 1]
    }
  ]
}

• errors.source (errors.content bei Kampagnen) listet bis zu fünf Fehlermeldungen auf, mit ihrer Zeile, wenn sie bekannt ist.
• diagnostics listet alle Diagnosen auf, auch Warnungen und Infos.
• Eine fehlende oder leere Quelle gibt 422 mit "message": "Validation failed", "errors": { "source": ["The source field is required for MJML."] } und einem leeren Array diagnostics zurück.

MJML validieren führt dieselben Prüfungen ohne Speichern aus und gibt statt 422 den Status 200 mit valid: false zurück.

Diagnosecodes

XML (Markup-Quellen)

MJML

Temple

Dokument und Compiler

Temple in MJML

Die Tags von Temple durchlaufen die MJML-Kompilierung unverändert. Emailit rendert sie beim Senden für jeden Empfänger, auf dem kompilierten HTML.

Variablen in Inhalten und Attributen

Variablen funktionieren im Inhalt und in jedem Attribut:

<mj-text>Hi {{first_name|"there"}},</mj-text>
<mj-button href="{{activation_url}}">Activate your account</mj-button>
<mj-image src="{{logo_url}}" alt="{{company|'Acme'}}" />
<mj-section background-color="{{brand_color|'#ffffff'}}">

• Schreiben Sie Standardwerte innerhalb eines Attributs mit einfachen Anführungszeichen: href="{{url|'https://example.com'}}".
• Attributwerte, die Temple enthalten, werden nicht auf ihren Typ geprüft, weil der Wert erst beim Senden feststeht. Stellen Sie sicher, dass die Variable einen Wert enthält, der für das Attribut gültig ist, etwa eine Farbe für background-color.
• Werte werden unverändert eingefügt, ohne HTML-Escaping.

Bedingungsblöcke

Innerhalb einer Komponente setzen Sie den Block in ihren Inhalt:

<mj-text>{{#if plan}}You are on the {{plan}} plan.{{else}}You are on the free plan.{{/if}}</mj-text>

Um ganze Komponenten ein- oder auszublenden, setzen Sie die Block-Tags in <mj-raw>-Elemente auf derselben Ebene:

<mj-raw>{{#if vip}}</mj-raw>
<mj-section background-color="#fef3c7">
  <mj-column>
    <mj-text>Your VIP perks are ready.</mj-text>
  </mj-column>
</mj-section>
<mj-raw>{{/if}}</mj-raw>

Freistehende Block-Tags zwischen Komponenten werden beim Parsen des Markups in <mj-raw> umgewandelt. Das hier ist also dasselbe:

{{#if vip}}
<mj-section background-color="#fef3c7">
  …
</mj-section>
{{/if}}

Anderer Text zwischen Komponenten wird von MJML ignoriert und als xml.stray-text gemeldet.

• Blöcke müssen im gesamten Dokument ausgeglichen sein. Ein nicht geschlossenes oder überzähliges Tag ist ein Fehler.
• Öffnen und schließen Sie jeden Block im Inhalt einer einzigen Komponente oder zwischen den <mj-raw>-Elementen desselben Elternelements. Ein Block, der in einer Komponente beginnt und in einer anderen endet, erhält die Warnung temple.block-crosses-components, weil sein Ausblenden mitten durch die HTML-Struktur schneiden würde.
• Blöcke lassen sich verschachteln.

Nicht unterstützt

• <mj-include> wird mit mjml.include-not-supported abgelehnt. Fügen Sie das eingebundene MJML direkt in das Dokument ein.
• Tags und Attribute, die MJML 5.4.1 nicht definiert, sind Fehler.
• Temple hat keine Schleifen, Helper, Partials, Kommentare, dreifachen geschweiften Klammern oder Vergleiche. Siehe Temple.

Variablen nach Kanal

Dieselbe MJML-Vorlage kann von mehreren Stellen aus gesendet werden, und jede liefert andere Variablen:

Die Editoren fügen eigene Felder als {{cf.<key>}} ein. Das funktioniert in MJML-Kampagnen und in Automatisierungen. Bei Versänden per API übergeben Sie die Variablen selbst.

Um die Version eines Empfängers in der Vorschau zu sehen, rufen Sie MJML rendern mit variables auf.

Kampagnen

Eine Kampagne mit content_type: "mjml" speichert ihr MJML in content, in einem der Quellformate, und Emailit kompiliert ihr html. Wie bei Vorlagen wird ein übergebenes html ignoriert. Ungültiges MJML gibt 422 mit errors.content und diagnostics zurück. Wenn Sie einen leeren content senden, werden sowohl der Inhalt als auch das HTML geleert. Antworten zu Kampagnen enthalten dasselbe Objekt mjml wie bei Vorlagen.

MJML-Kampagnen rendern Betreff, HTML und Text für jeden Empfänger mit Temple, auch bei Testversänden. Diese Variablen stehen zur Verfügung:

Leere Kontaktfelder gelten als fehlend, daher greifen Standardwerte: {{first_name|"there"}} ergibt there bei einem Kontakt ohne Vornamen. Behalten Sie in Marketing-E-Mails einen Link mit {{unsubscribe_url}} in der Fußzeile.

Klassische Kampagnen (HTML, Text und die anderen Editoren) behalten die festen Platzhalter:

Wenn Sie in der Weboberfläche eine Kampagne aus einer MJML-Vorlage starten, wird das MJML-Dokument der Vorlage in die Kampagne kopiert.

Ohne MJML-Zugriff

Während der Alpha kompiliert Emailit das MJML von Kampagnen nur für das Emailit-Team. Für alle anderen, auch für API-Schlüssel, bleibt content_type: "mjml" die reine Bezeichnung, die es vor der Alpha war: content wird so gespeichert, wie Sie es senden, Sie senden das kompilierte HTML in html, und Versände verwenden die klassischen Platzhalter. Wenn Sie eine Kampagne aus einer MJML-Vorlage starten, wird das HTML der Vorlage in eine HTML-Kampagne kopiert.

Automatisierungen

Der Schritt Send email verweist über ihre ID (tem_…) auf eine Vorlage. MJML-Vorlagen funktionieren wie alle anderen: Der Schritt sendet das kompilierte HTML der Vorlage und rendert Temple mit den Variablen der Automatisierung. Siehe E-Mails aus Automatisierungen.

In den Einstellungen des Schritts erstellt Design a new email eine MJML-Vorlage aus einem Startdesign, wählt sie für den Schritt aus und öffnet sie im Visual Editor. Edit email öffnet die ausgewählte MJML-Vorlage. Änderungen wirken auf die Vorlage selbst, sodass jeder Schritt und jeder API-Aufruf, der die Vorlage verwendet, sie übernimmt. Ohne MJML-Zugriff zeigt der Schritt stattdessen einen Link zur Vorlage.

Gemeinsam bearbeiten

Alle, die dieselbe gespeicherte MJML-Vorlage oder -Kampagne öffnen, bearbeiten in Echtzeit einen gemeinsamen Entwurf, in beiden Editoren:

• Anwesenheit: Die Kopfzeile zeigt, wer außerdem bearbeitet und was die anderen gerade tun. Im Visual Editor sehen Sie ihre Auswahl, ihre Cursor und eine kurze Hervorhebung in ihrer Farbe, wo sie etwas ändern. Layers zeigt, wer eine Komponente ausgewählt hat. Wählen Sie den Avatar einer Person, um zu ihrer Auswahl zu springen.
• Änderungen werden zusammengeführt: Änderungen an verschiedenen Komponenten, Attributen oder Textteilen werden kombiniert, statt sich gegenseitig zu überschreiben. Während jemand auf der Arbeitsfläche in einen Text tippt, ist dieser Text für andere gesperrt.
• Code Editor: Ihre Änderungen fließen beim Tippen in den gemeinsamen Entwurf ein. Änderungen anderer erscheinen in Ihrem Code, sobald Sie eine Tipppause machen, damit Ihr Cursor nicht springt. Enthält Ihr Code einen Syntaxfehler, warten sie, bis Sie ihn behoben haben.
• Rückgängig und Wiederholen wirken nur auf Ihre eigenen Änderungen.
• Speichern: Es gibt ein einziges Save für alle. Die Kopfzeile zeigt ungespeicherte Änderungen für den gesamten Entwurf und wer zuletzt gespeichert hat. Der Versand verwendet immer die gespeicherte Version.
• Der Entwurf bleibt erhalten: Wenn Sie den Editor schließen oder die Verbindung verlieren, gehen keine Änderungen verloren. Sie bleiben im gemeinsamen Entwurf und werden synchronisiert, sobald Sie wieder online sind. Beim erneuten Öffnen des Editors werden ungespeicherte Änderungen wiederhergestellt, und Sie können sie verwerfen, um zur gespeicherten Version zurückzukehren.
• Anderswo gespeichert: Wird die Vorlage oder Kampagne außerhalb des Editors gespeichert (per API, MCP oder Edit with AI), während sie geöffnet ist, wechselt ein Entwurf ohne ungespeicherte Änderungen zur gespeicherten Version. Ein Entwurf mit ungespeicherten Änderungen behält sie und bietet Load saved version oder Keep this draft an.
• Gelöscht: Wird die Vorlage oder Kampagne gelöscht oder ist sie kein MJML mehr, während Sie sie bearbeiten, teilt Ihnen der Editor das mit und lässt Sie das MJML kopieren.

Gemeinsames Bearbeiten erfordert gespeichertes, gültiges MJML. Eine Vorlage oder Kampagne, deren MJML sich nicht parsen lässt oder die noch nicht als MJML gespeichert ist, öffnet sich ohne diese Funktion: Jede Person bearbeitet allein, und das letzte Speichern gewinnt. Der Editor weist in einem Banner darauf hin. In einem gesperrten Workspace sind die Editoren schreibgeschützt.

Versionen und Upgrades

Emailit kompiliert mit jeweils einer MJML-Version, derzeit 5.4.1. Jedes gespeicherte Dokument hält die mjml_version fest, auf die es ausgelegt ist, und Emailit prüft sie bei jeder Kompilierung des Dokuments:

Ein Dokument, dessen schema_version neuer ist als die, die Emailit lesen kann, wird mit document.unsupported-schema abgelehnt. Beim Speichern wird das Dokument mit der aktuellen mjml_version und schema_version gespeichert. Prüfen Sie nach einem Upgrade die Vorschau.

Die Editoren zeigen ihre Version und ihr Changelog an. Wurde ein Dokument mit einer neueren Editor-Version gespeichert als der der geöffneten Seite, fordert der Editor Sie auf, die Seite neu zu laden.

MJML für KI-Agenten

MJML-Referenz abrufen gibt Tools und KI-Modellen, was sie brauchen, um gültiges MJML für Emailit zu schreiben: jede Komponente mit ihren erlaubten Eltern- und Kindelementen und Attributen (Typ und Standardwert), den Temple-Leitfaden, Regeln zum Verfassen von MJML und einen kompakten Nur-Text reference_text für Prompts.

Auf dem MCP-Server erhalten Sitzungen des Emailit-Teams außerdem diese Tools im Toolset templates:

Scheitert ein Speichern an der Validierung, listet der Tool-Fehler die Diagnosen der Stufen Fehler und Warnung mit ihren Zeilennummern auf, damit der Agent die Quelle korrigieren kann. Ein typischer Ablauf: die Referenz lesen, das MJML schreiben, validate-mjml aufrufen, bis valid den Wert true hat, mit create-template speichern und dann mit render-mjml die Version eines Empfängers prüfen. Andere Sitzungen sehen diese Tools und Parameter nicht.

In der Weboberfläche

• Vorlagen: Erstellen Sie eine Vorlage und wählen Sie MJML Visual Editor (Alpha) oder MJML Code Editor (Alpha).
• Visual Editor: Drag-and-drop auf der gerenderten E-Mail, ein Ebenenbaum, ein Eigenschaftenbereich für jedes MJML-Attribut, Dokumenteinstellungen (Head, Schriften, Stile und Standardattribute), Temple-Variablen in jeder Eigenschaft und Bedingungsblöcke um Komponenten.
• Code Editor: Autovervollständigung für MJML-Tags, Attribute, Werte und Temple, Inline-Validierung mit Schnellkorrekturen und Formatierung.
• Beide Editoren: eine Live-Vorschau für Desktop und Mobilgeräte, im Browser mit MJML 5.4.1 kompiliert, eine Vorschau mit Beispieldaten (Temple gerendert), eine Problemliste und ein KI-Assistent, wenn er aktiviert ist. Sie können für dasselbe Dokument zwischen Visual und Code wechseln; der Wechsel zu Visual erfordert Code ohne Syntaxfehler. Speichern ist blockiert, solange das MJML Fehler enthält.
• Gemeinsam bearbeiten: Teammitglieder, die dieselbe Vorlage oder Kampagne öffnen, bearbeiten sie in Echtzeit. Siehe Gemeinsam bearbeiten.
• Edit with AI: Beschreiben Sie eine Änderung an einer MJML-Vorlage oder -Kampagne, ohne den Editor zu öffnen.
• Import: eine .mjml-Datei, eine .json-Datei mit MJML-JSON oder einem Emailit-MJML-Dokument oder ein ZIP mit template.mjml und einem Ordner images/ auf oberster Ebene.
• Export: MJML (Markup), MJML-JSON (das gespeicherte Dokument), HTML oder ein ZIP mit template.mjml, template.html und images/. Der Export funktioniert für alle.
• Kampagnen: Wählen Sie für den Inhalt der Kampagne den MJML Visual Editor oder den MJML Code Editor.
• Automatisierungen: Gestalten Sie die E-Mail eines Schritts Send email direkt dort. Siehe Automatisierungen.

Siehe auch

• Vorlagen erstellen und bearbeiten
• Template-Sprache Temple
• API-Referenz für MJML
• Import und Export