Editory a API pro MJML

MJML je značkovací jazyk pro responzivní e-maily. Píšete sekce, sloupce a komponenty, například <mj-text> a <mj-button>, a MJML je zkompiluje do HTML, které se v různých e-mailových klientech vykreslí stejně. V Emailitu může být MJML zdrojem šablony nebo kampaně: napíšete ho v editorech ve webovém rozhraní, nebo ho pošlete přes API, a Emailit ho zvaliduje a zkompiluje z něj HTML.

Přehled

• Šablony: editor: "mjml" a MJML v source. Viz Vytvoření šablony.
• Kampaně: content_type: "mjml" a MJML v content. Viz Kampaně.
• Automatizace: krok Send email odešle šablonu MJML stejně jako kteroukoli jinou šablonu. Viz Automatizace.
• Endpointy MJML: Validace MJML, Vykreslení MJML a Načtení reference MJML.

Kdo může MJML používat

Během alfaverze je MJML dostupné jen administrátorům platformy Emailit. Role Admin ve workspace nestačí.

Přejmenovat, publikovat, vyexportovat, odeslat a smazat šablony a kampaně MJML může i nadále kdokoli. Duplikací šablony MJML vznikne nová šablona MJML, takže k ní potřebujete přístup k MJML.

Verze MJML

Emailit kompiluje veškeré MJML pomocí MJML 5.4.1, na serveru i v živém náhledu v editorech. Validace kontroluje tagy, atributy a hodnoty atributů podle této verze. Endpoint Načtení reference MJML vrací tuto verzi a všechny komponenty a atributy, které podporuje.

Editory

Webové rozhraní má dva editory MJML. Oba mají vlastní verze a oba jsou alfaverze 0.x.

Oba editory ukládají šablonu s editor: "mjml". Uložený dokument zaznamenává, který editor a v jaké verzi ho naposledy uložil. Kolegové mohou stejnou šablonu nebo kampaň upravovat současně. Viz Společné úpravy.

Formáty zdroje

Všude, kde Emailit přijímá MJML (pole source u šablony, content u kampaně a pole source u endpointů MJML), můžete poslat kterýkoli z těchto formátů:

Cokoli jiného Emailit odmítne s kódem document.unrecognized. Zdroje větší než 2 MB odmítne s kódem document.too-large.

Uložený dokument

Emailit ukládá MJML do obálky s verzí. Je to source šablony a content kampaně:

{
  "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>"
}

Formát určuje to, co pošlete: značkování se uloží jako markup a MJML JSON jako json. Obojí se zaznamená jako editor: "api". Obálka, kterou pošlete, si ponechá svůj editor a editor_version.

Odpovědi API vracejí source jako tuto obálku převedenou na řetězec JSON a můžete ji poslat zpět beze změny. Odpovědi také obsahují objekt mjml s verzemi obálky:

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

Webové rozhraní otevře dokument v editoru, který ho naposledy uložil. Dokumenty zapsané přes API se otevřou v editoru kódu, když má format hodnotu markup, a ve vizuálním editoru, když má hodnotu json.

Kompilace a uložení

U šablon a kampaní MJML spravuje HTML Emailit:

• Při vytvoření a úpravě Emailit MJML zvaliduje a zkompiluje. Zkompilované HTML se uloží jako html šablony a jakékoli html, které pošlete, se ignoruje.
• Při odesílání se použije uložené HTML. Značky Temple v něm zůstávají a vykreslí se pro každého příjemce při odeslání.
• Když upravíte jen jiná pole, například name nebo subject, MJML se znovu nekompiluje.
• text se z MJML negeneruje. Pokud chcete část v prostém textu, pošlete text sami.
• Když existující šablonu přepnete na editor: "mjml" a nepošlete source, zkompiluje se uložený source šablony, který pak musí být MJML.

HTML se kompiluje při uložení, takže HTML existující šablony se změní, až když ji znovu uložíte.

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>"
  }'

Pak ji odešlete jako kteroukoli jinou šablonu endpointem Odeslání e-mailu: s "template": "welcome" a objektem variables.

Validace

Každé uložení provede stejné kontroly jako Validace MJML:

• Syntaxe XML: neuzavřené nebo nepárové tagy a poškozené atributy (xml.*)
• Struktura MJML, atributy a hodnoty atributů pro MJML 5.4.1 (mjml.*)
• Syntaxe Temple a spárované bloky {{#if}} (temple.*)
• Formát zdroje a verze (document.*) a samotný kompilátor (compiler.*)

Každé zjištění je diagnostické hlášení se závažností:

Hlášení má tato pole. Pole, která se ho netýkají, se vynechávají.

Chybová odpověď

Uložení šablony nebo kampaně s chybovými hlášeními vrací 422. Pro tento zdroj:

<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>

vypadá odpověď takto:

{
  "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 (u kampaní errors.content) uvádí nejvýše pět chybových zpráv, a pokud je řádek známý, i s ním.
• diagnostics uvádí všechna hlášení včetně varování a informací.
• Chybějící nebo prázdný zdroj vrací 422 s "message": "Validation failed", "errors": { "source": ["The source field is required for MJML."] } a prázdným polem diagnostics.

Validace MJML provede stejné kontroly bez uložení a místo 422 vrací 200 s valid: false.

Kódy hlášení

XML (zdroje ve značkování)

MJML

Temple

Dokument a kompilátor

Temple v MJML

Značky Temple projdou kompilací MJML beze změny. Emailit je vykreslí pro každého příjemce při odeslání, a to ve zkompilovaném HTML.

Proměnné v obsahu a atributech

Proměnné fungují v obsahu i v jakémkoli atributu:

<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'}}">

• Uvnitř atributu pište výchozí hodnoty v jednoduchých uvozovkách: href="{{url|'https://example.com'}}".
• U hodnot atributů, které obsahují Temple, se typ nekontroluje, protože hodnota je známá až při odeslání. Zajistěte, aby proměnná obsahovala hodnotu platnou pro daný atribut, například barvu pro background-color.
• Hodnoty se vkládají tak, jak jsou, bez escapování HTML.

Podmíněné bloky

V rámci jedné komponenty dejte blok do jejího obsahu:

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

Pokud chcete zobrazit nebo skrýt celé komponenty, dejte značky bloku do sourozeneckých prvků <mj-raw>:

<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>

Samostatné značky bloků mezi komponentami se při zpracování značkování převedou na <mj-raw>, takže tohle je totéž:

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

Ostatní text mezi komponentami MJML ignoruje a validace ho hlásí jako xml.stray-text.

• Bloky musí být spárované v celém dokumentu. Neuzavřená nebo přebytečná značka je chyba.
• Každý blok otevřete i uzavřete v obsahu jedné komponenty, nebo mezi sourozeneckými prvky <mj-raw> jednoho rodiče. Blok, který se otevírá v jedné komponentě a zavírá v jiné, dostane varování temple.block-crosses-components, protože jeho skrytí by rozdělilo strukturu HTML.
• Bloky lze vnořovat.

Co se nepodporuje

• <mj-include> se odmítne s kódem mjml.include-not-supported. Vložené MJML zkopírujte přímo do dokumentu.
• Tagy a atributy, které MJML 5.4.1 nedefinuje, jsou chyby.
• Temple nemá cykly, pomocné funkce, dílčí šablony, komentáře, trojité závorky ani porovnání. Viz Temple.

Proměnné podle kanálu

Stejnou šablonu MJML lze odeslat z několika míst a každé z nich poskytuje jiné proměnné:

Editory vkládají vlastní pole jako {{cf.<key>}}, což funguje v kampaních MJML i v automatizacích. Při odesílání přes API předejte proměnné sami.

Verzi pro konkrétního příjemce si zobrazíte, když zavoláte Vykreslení MJML s variables.

Kampaně

Kampaň s content_type: "mjml" ukládá své MJML do content v kterémkoli z formátů zdroje a Emailit z něj zkompiluje její html. Stejně jako u šablon se jakékoli html, které pošlete, ignoruje. Neplatné MJML vrací 422 s errors.content a diagnostics. Když pošlete prázdný content, smaže se obsah i HTML. Odpovědi pro kampaně obsahují stejný objekt mjml jako šablony.

Kampaně MJML vykreslují předmět, HTML a text jazykem Temple pro každého příjemce, a to i u testovacích e-mailů. K dispozici jsou tyto proměnné:

Prázdná pole kontaktu se počítají jako chybějící, takže se použijí výchozí hodnoty: {{first_name|"there"}} vykreslí u kontaktu bez křestního jména there. V patičce marketingových e-mailů ponechte odkaz {{unsubscribe_url}}.

Klasické kampaně (HTML, text a ostatní editory) dál používají pevné slučovací značky:

Když ve webovém rozhraní založíte kampaň ze šablony MJML, zkopíruje se dokument MJML šablony do kampaně.

Bez přístupu k MJML

Během alfaverze Emailit kompiluje MJML kampaní jen pro tým Emailitu. Pro všechny ostatní, včetně API klíčů, zůstává content_type: "mjml" pouhým označením jako před alfaverzí: content se uloží tak, jak ho pošlete, zkompilované HTML posíláte v html a při odesílání se použijí klasické slučovací značky. Když kampaň založíte ze šablony MJML, zkopíruje se HTML šablony do kampaně typu HTML.

Automatizace

Krok Send email odkazuje na šablonu podle ID (tem_…). Šablony MJML fungují jako kterékoli jiné: krok odešle zkompilované HTML šablony a vykreslí Temple s proměnnými automatizace. Viz E-maily z automatizací.

V nastavení kroku tlačítko Design a new email vytvoří šablonu MJML z úvodního designu, vybere ji pro krok a otevře ji ve vizuálním editoru. Tlačítko Edit email otevře vybranou šablonu MJML. Úpravy mění samotnou šablonu, takže se projeví v každém kroku a volání API, které tuto šablonu používá. Bez přístupu k MJML krok místo toho zobrazí odkaz na šablonu.

Společné úpravy

Každý, kdo otevře stejnou uloženou šablonu nebo kampaň MJML, upravuje v reálném čase jeden sdílený koncept, a to v kterémkoli z obou editorů:

• Přítomnost: záhlaví ukazuje, kdo další upravuje a co právě dělá. Ve vizuálním editoru vidíte jejich výběry, kurzory a krátké zvýraznění v jejich barvě tam, kde něco mění. Panel Layers ukazuje, kdo má kterou komponentu vybranou. Výběrem avataru přeskočíte na výběr daného člověka.
• Úpravy se slučují: změny různých komponent, atributů nebo částí textu se spojí, místo aby se navzájem přepsaly. Zatímco někdo píše do textu na plátně, je tento text pro ostatní zamčený.
• Editor kódu: vaše změny se do sdíleného konceptu slučují průběžně, jak píšete. Změny ostatních se ve vašem kódu objeví, až přestanete psát, aby vám neposkakoval kurzor. Pokud má váš kód syntaktickou chybu, počkají, dokud ji neopravíte.
• Zpět a znovu vracejí jen vaše vlastní změny.
• Ukládání: pro všechny je jedno tlačítko Save. Záhlaví ukazuje neuložené změny celého konceptu a kdo naposledy ukládal. Odesílá se vždy uložená verze.
• Koncept zůstává: zavřením editoru ani výpadkem připojení o změny nepřijdete. Zůstanou ve sdíleném konceptu a synchronizují se, až budete znovu online. Po opětovném otevření editoru se neuložené změny obnoví a můžete je zahodit a vrátit se k uložené verzi.
• Uloženo jinde: když se šablona nebo kampaň uloží mimo editor (přes API, MCP nebo Edit with AI), zatímco je otevřená, koncept bez neuložených změn se přepne na uloženou verzi. Koncept s neuloženými změnami si je ponechá a nabídne Load saved version, nebo Keep this draft.
• Smazáno: pokud se šablona nebo kampaň během úprav smaže nebo přestane být MJML, editor vás na to upozorní a nechá vás MJML zkopírovat.

Společné úpravy vyžadují uložené a platné MJML. Šablona nebo kampaň, jejíž MJML nejde zpracovat, nebo která ještě není uložená jako MJML, se otevře bez nich: každý upravuje sám a platí poslední uložení. Editor na to upozorní v banneru. V zablokovaném workspace jsou editory jen pro čtení.

Verze a aktualizace

Emailit kompiluje vždy jednou verzí MJML, aktuálně 5.4.1. Každý uložený dokument zaznamenává mjml_version, pro kterou je určený, a Emailit ji kontroluje při každé kompilaci dokumentu:

Dokument, jehož schema_version je novější, než Emailit umí číst, se odmítne s document.unsupported-schema. Při uložení se dokument uloží s aktuální mjml_version a schema_version. Po aktualizaci zkontrolujte náhled.

Editory zobrazují svou verzi a přehled změn. Když byl dokument uložen novější verzí editoru, než jakou má stránka, kterou máte otevřenou, editor vás požádá o její obnovení.

MJML pro AI agenty

Načtení reference MJML dává nástrojům a AI modelům vše, co potřebují k psaní platného MJML pro Emailit: každou komponentu s povolenými rodiči, potomky a atributy (typ a výchozí hodnota), průvodce jazykem Temple, pravidla pro psaní MJML a kompaktní reference_text v prostém textu pro prompty.

Na MCP serveru dostávají relace týmu Emailitu v sadě nástrojů templates navíc tyto nástroje:

Když uložení neprojde validací, chyba nástroje uvede chybová hlášení a varování s čísly řádků, aby agent mohl zdroj opravit. Typický postup: přečíst referenci, napsat MJML, volat validate-mjml, dokud valid není true, uložit pomocí create-template a pak zkontrolovat verzi pro příjemce pomocí render-mjml. Ostatní relace tyto nástroje ani parametry nevidí.

Ve webovém rozhraní

• Šablony: vytvořte šablonu a zvolte MJML Visual Editor (Alpha), nebo MJML Code Editor (Alpha).
• Vizuální editor: drag & drop přímo na vykresleném e-mailu, strom vrstev, panel vlastností pro každý atribut MJML, nastavení dokumentu (hlavička, písma, styly a výchozí atributy), proměnné Temple v jakékoli vlastnosti a podmíněné bloky kolem komponent.
• Editor kódu: automatické doplňování tagů, atributů a hodnot MJML i jazyka Temple, průběžná validace s rychlými opravami a formátování.
• Oba editory: živý náhled pro počítač i mobil kompilovaný v prohlížeči pomocí MJML 5.4.1, náhled s ukázkovými daty (s vykresleným Temple), seznam problémů a AI asistent, pokud je zapnutý. U stejného dokumentu můžete přepínat mezi vizuálním editorem a editorem kódu; přepnutí do vizuálního editoru vyžaduje kód bez syntaktických chyb. Dokud MJML obsahuje chyby, nejde ho uložit.
• Společné úpravy: kolegové, kteří otevřou stejnou šablonu nebo kampaň, ji upravují v reálném čase. Viz Společné úpravy.
• Edit with AI: popište změnu šablony nebo kampaně MJML, aniž byste otevírali editor.
• Import: soubor .mjml, soubor .json s MJML JSON nebo dokumentem MJML Emailitu, nebo ZIP s template.mjml a složkou images/ v kořeni.
• Export: MJML (značkování), MJML JSON (uložený dokument), HTML, nebo ZIP s template.mjml, template.html a images/. Export funguje pro všechny.
• Kampaně: pro obsah kampaně zvolte MJML Visual Editor, nebo MJML Code Editor.
• Automatizace: e-mail kroku Send email navrhnete přímo na místě. Viz Automatizace.

Související

• Vytváření a úprava šablon
• Šablonovací jazyk Temple
• Reference API pro MJML
• Import a export šablon