Zum Inhalt springen
Doku

MJML (Alpha)

MJML validieren und rendern und die MJML-Referenz lesen. In der Alpha und nur für das Emailit-Team zugänglich.

Basis-URLhttps://api.emailit.com/v2AuthentifizierungFehlerRate Limits

MJML validieren

Prüft MJML wie beim Speichern einer Vorlage (XML-Syntax, MJML-Struktur, Attributtypen und Temple-Syntax) und kompiliert es mit MJML 5.4.1. Es wird nichts gespeichert. Ungültiges MJML gibt trotzdem 200 zurück, mit valid: false und den Diagnosen. Erfordert den Scope full.

Was die einzelnen Prüfungen abdecken, erfahren Sie unter Validierung.

POST/mjml/validate

Body-Parameter

sourcestring | objectErforderlich

Das zu prüfende MJML: MJML-Markup (<mjml>…</mjml>), MJML-JSON oder ein Emailit-MJML-Dokument, etwa das gespeicherte source einer Vorlage. Siehe Quellformate. Höchstens 2 MB.

Rückgabe

Gibt 200 OK mit dem Ergebnis zurück, auch wenn das MJML ungültig ist:

Feld Typ Beschreibung
valid boolean true, wenn es keine Fehlerdiagnosen gibt, sich eine Vorlage mit dieser Quelle also speichern lässt.
mjml_version string Die MJML-Version, mit der Emailit kompiliert.
format string oder null Wie die Quelle gelesen wurde: markup oder json. null, wenn sie nicht gelesen werden konnte.
diagnostics array Alle Diagnosen der Stufen Fehler, Warnung und Info.

valid: true bedeutet, dass eine Vorlage mit dieser Quelle angenommen würde. Beheben Sie auch die Warnungen: Sie weisen meist auf echte Probleme hin, etwa ein fehlendes <mj-title>. Das HTML erhalten Sie mit MJML rendern.

Gibt 422 mit message: "Validation failed" zurück, wenn source fehlt oder leer ist, und 403 mit error: "mjml_alpha" ohne MJML-Zugriff.

Diagnose-Objekt

Felder, die nicht zutreffen, werden weggelassen.

Feld Typ Beschreibung
severity string error, warning oder info. Nur Fehler setzen valid auf false.
code string Ein stabiler Code, zum Beispiel mjml.invalid-child, xml.unclosed-tag oder temple.unclosed-if. Siehe Diagnosecodes.
message string Eine verständliche Erklärung.
line integer Zeile im Markup, ab 1 gezählt. Nur bei Markup-Quellen.
column integer Spalte im Markup, ab 1 gezählt. Nur bei Markup-Quellen.
tag string Das Element, auf das sich die Diagnose bezieht.
attribute string Das Attribut, auf das sich die Diagnose bezieht.
path integer[] Pfad aus Kindindizes ab der Wurzel <mjml>.
POST/mjml/validate
Terminal
curl -X POST https://api.emailit.com/v2/mjml/validate \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "<mjml>\n  <mj-body>\n    <mj-column>\n      <mj-text colour=\"#333333\">Hi {{first_name}}</mj-text>\n    </mj-column>\n  </mj-body>\n</mjml>"
  }'
JSON
{
  "valid": false,
  "mjml_version": "5.4.1",
  "format": "markup",
  "diagnostics": [
    {
      "severity": "error",
      "code": "mjml.invalid-child",
      "message": "<mj-column> cannot be placed inside <mj-body>. Allowed parents: <mj-group>, <mj-section>.",
      "line": 3,
      "column": 6,
      "tag": "mj-column",
      "path": [0, 0]
    },
    {
      "severity": "error",
      "code": "mjml.unknown-attribute",
      "message": "<mj-text> has no attribute colour. Did you mean color?",
      "line": 4,
      "column": 16,
      "tag": "mj-text",
      "attribute": "colour",
      "path": [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": []
    }
  ]
}

MJML rendern

Kompiliert MJML mit MJML 5.4.1 zu dem HTML, das Emailit sendet. Mit variables enthält die Antwort außerdem rendered_html: das HTML, nachdem Temple angewendet wurde, so wie ein einzelner Empfänger es erhalten würde. Es wird nichts gespeichert oder gesendet. Erfordert den Scope full.

Dieser Endpunkt ist auf 120 Anfragen pro Minute begrenzt.

POST/mjml/render

Body-Parameter

sourcestring | objectErforderlich

Das zu kompilierende MJML: MJML-Markup (<mjml>…</mjml>), MJML-JSON oder ein Emailit-MJML-Dokument, etwa das gespeicherte source einer Vorlage. Siehe Quellformate. Höchstens 2 MB.

variablesobject

Temple-Variablen für rendered_html, etwa first_name, oder ein Objekt cf mit eigenen Feldern für Kampagnen. Nichts wird automatisch befüllt: Übergeben Sie die Variablen, die der sendende Kanal liefern würde. Siehe Variablen nach Kanal. Muss ein Objekt sein; alles andere gibt 400 zurück.

Rückgabe

Gibt 200 OK mit dem Ergebnis zurück, auch wenn das MJML ungültig ist:

Feld Typ Beschreibung
valid boolean true, wenn es keine Fehlerdiagnosen gibt.
mjml_version string Die MJML-Version, mit der Emailit kompiliert.
html string oder null Das kompilierte HTML mit unveränderten Temple-Tags, so wie Emailit es für eine Vorlage speichert. null, wenn das MJML Fehler enthält.
html_bytes integer UTF-8-Größe von html. Gmail kürzt Nachrichten ab etwa 102 KB. 0, wenn html null ist.
diagnostics array Alle Diagnosen der Stufen Fehler, Warnung und Info. Siehe MJML validieren.
rendered_html string oder null html, nachdem Temple die variables angewendet hat. Nur vorhanden, wenn Sie variables senden, und null, wenn das MJML Fehler enthält.

Ungültiges MJML gibt 200 mit valid: false, html: null und den Diagnosen zurück. rendered_html verwendet genau die variables, die Sie senden: Fehlende Variablen werden als leere Strings oder als ihr Standardwert gerendert, {{first_name|"there"}} ergibt also there. Aus MJML wird kein Nur-Text erzeugt.

Gibt 422 mit message: "Validation failed" zurück, wenn source fehlt oder leer ist, 400, wenn variables kein Objekt ist, und 403 mit error: "mjml_alpha" ohne MJML-Zugriff.

POST/mjml/render
Terminal
curl -X POST https://api.emailit.com/v2/mjml/render \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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>",
    "variables": {
      "first_name": "Ada",
      "activation_url": "https://example.com/activate?token=abc123"
    }
  }'
JSON
{
  "valid": true,
  "mjml_version": "5.4.1",
  "html": "<!doctype html>\n<html lang=\"und\" dir=\"auto\" …>…Hi {{first_name|\"there\"}}, welcome aboard.…<a href=\"{{activation_url}}\" …>…</html>\n",
  "html_bytes": 5267,
  "diagnostics": [],
  "rendered_html": "<!doctype html>\n<html lang=\"und\" dir=\"auto\" …>…Hi Ada, welcome aboard.…<a href=\"https://example.com/activate?token=abc123\" …>…</html>\n"
}

MJML-Referenz abrufen

Ruft alle MJML-Komponenten und -Attribute der MJML-Version ab, mit der Emailit kompiliert, dazu die aktuellen Editor-Versionen, den Temple-Leitfaden und die Regeln zum Verfassen von MJML. Damit können Sie Tools entwickeln oder einem KI-Modell geben, was es zum Schreiben gültiger MJML-Vorlagen braucht. Erfordert den Scope full.

Dieselbe Referenz steht KI-Agenten als MCP-Tool get-mjml-reference zur Verfügung. Siehe MJML für KI-Agenten.

GET/mjml/reference

Rückgabe

Gibt 200 OK mit der Referenz zurück. Das Beispiel oben ist gekürzt: components listet alle 36 Komponenten mit allen ihren Attributen auf.

Feld Typ Beschreibung
mjml_version string Die MJML-Version, mit der Emailit kompiliert.
document_schema_version integer Die aktuelle schema_version des gespeicherten MJML-Dokuments.
editors object Aktuelle Version und Stufe (alpha, beta oder stable) von mjml-code und mjml-visual.
components array Alle MJML-Komponenten. Siehe unten.
temple_guide string Wie Temple in MJML funktioniert: Variablen, Standardwerte, Bedingungen und Kampagnenvariablen.
rules string Regeln zum Verfassen von MJML: Struktur, erlaubte Attribute und Barrierefreiheit.
reference_text string Die gesamte Komponentenreferenz als kompakter Nur-Text, für Prompts.

Gibt ohne MJML-Zugriff 403 mit error: "mjml_alpha" zurück.

Komponenten-Objekt

Feld Typ Beschreibung
tag string Tag-Name, zum Beispiel mj-button.
label string Anzeigename.
description string Was die Komponente tut.
category string root, head, layout, content, interactive, child oder advanced.
ending_tag boolean true, wenn der Inhalt rohes HTML oder Text ist (mj-text, mj-button, mj-raw, …).
parents string[] Elemente, in die diese Komponente gesetzt werden kann.
children string[] Elemente, die diese Komponente enthalten kann. ["*"] bedeutet jede beliebige Komponente (mj-attributes).
attributes array Attribute, jeweils mit name, type (ein MJML-Typ wie color, unit(px,%){1,4} oder enum(left,center,right)) und default (null, wenn es keinen gibt).
GET/mjml/reference
Terminal
curl https://api.emailit.com/v2/mjml/reference \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "mjml_version": "5.4.1",
  "document_schema_version": 1,
  "editors": {
    "mjml-code": { "version": "0.2.0", "stage": "alpha" },
    "mjml-visual": { "version": "0.2.0", "stage": "alpha" }
  },
  "components": [
    {
      "tag": "mj-body",
      "label": "Body",
      "description": "The visible email. Holds sections, wrappers and heroes.",
      "category": "root",
      "ending_tag": false,
      "parents": ["mjml"],
      "children": ["mj-raw", "mj-section", "mj-wrapper", "mj-hero"],
      "attributes": [
        { "name": "width", "type": "unit(px)", "default": "600px" },
        { "name": "background-color", "type": "color", "default": null },
        { "name": "id", "type": "string", "default": null },
        { "name": "mj-class", "type": "string", "default": null },
        { "name": "css-class", "type": "string", "default": null }
      ]
    },
    {
      "tag": "mj-button",
      "label": "Button",
      "description": "A bulletproof call-to-action button. Content is the label.",
      "category": "content",
      "ending_tag": true,
      "parents": ["mj-column", "mj-hero"],
      "children": [],
      "attributes": [
        { "name": "align", "type": "enum(left,center,right)", "default": "center" },
        { "name": "background-color", "type": "color", "default": "#414141" },
        { "name": "href", "type": "string", "default": null },
        { "name": "inner-padding", "type": "unit(px,%){1,4}", "default": "10px 25px" }
      ]
    }
  ],
  "temple_guide": "Temple is Emailit's templating language, evaluated per recipient at send time on the final HTML:\n- {{first_name}} inserts a variable; …",
  "rules": "MJML rules:\n- Structure: <mjml> > <mj-head> (optional) + <mj-body>. …",
  "reference_text": "MJML 5.4.1 component reference. Format: name=type[default]. …"
}

War diese Seite hilfreich?

Danke für Ihr Feedback.

Danke, wir lesen jede Nachricht.

Esc

Beliebt

↑↓zum Navigieren↵zum ÖffnenEsczum Schließen