Éditeurs et API MJML

MJML est un langage de balisage pour les e-mails responsives. Vous écrivez des sections, des colonnes et des composants comme <mj-text> et <mj-button>, et MJML les compile en un HTML qui s’affiche de façon homogène dans les clients de messagerie. Dans Emailit, MJML peut être la source d’un modèle ou d’une campagne : vous l’écrivez dans les éditeurs du tableau de bord ou l’envoyez via l’API, et Emailit le valide et compile le HTML.

Vue d’ensemble

• Modèles : editor: "mjml" avec le MJML dans source. Consultez Créer un modèle.
• Campagnes : content_type: "mjml" avec le MJML dans content. Consultez Campagnes.
• Automatisations : l’étape Send email envoie un modèle MJML comme n’importe quel autre modèle. Consultez Automatisations.
• Endpoints MJML : Valider du MJML, Effectuer le rendu de MJML et Récupérer la référence MJML.

Qui peut utiliser MJML

Pendant l’alpha, MJML est disponible uniquement pour les administrateurs de la plateforme Emailit. Le rôle Admin d’un espace de travail ne suffit pas.

Tout le monde peut toujours renommer, publier, exporter, envoyer et supprimer les modèles et les campagnes MJML. Dupliquer un modèle MJML crée un nouveau modèle MJML : cette action nécessite donc l’accès à MJML.

Version de MJML

Emailit compile tout le MJML avec MJML 5.4.1, sur le serveur comme dans l’aperçu en direct des éditeurs. La validation vérifie les balises, les attributs et les valeurs d’attribut par rapport à cette version. Récupérer la référence MJML renvoie la version ainsi que chaque composant et chaque attribut qu’elle prend en charge.

Éditeurs

Le tableau de bord propose deux éditeurs MJML. Tous deux sont versionnés, et tous deux sont des versions alpha 0.x.

Les deux éditeurs enregistrent un modèle avec editor: "mjml". Le document enregistré indique quel éditeur, et quelle version de cet éditeur, l’a enregistré en dernier. Vos collègues peuvent modifier le même modèle ou la même campagne en même temps. Consultez Édition collaborative.

Formats de source

Partout où Emailit accepte du MJML (le source d’un modèle, le content d’une campagne et le champ source des endpoints MJML), vous pouvez envoyer l’un de ces formats :

Tout autre contenu est rejeté avec document.unrecognized. Les sources de plus de 2 Mo sont rejetées avec document.too-large.

Le document enregistré

Emailit enregistre le MJML dans une enveloppe versionnée. C’est le source du modèle et le content de la campagne :

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

Ce que vous envoyez détermine le format : le balisage est enregistré en markup et le MJML JSON en json. Les deux sont enregistrés avec editor: "api". Une enveloppe que vous envoyez conserve son editor et son editor_version.

Les réponses de l’API renvoient source sous la forme de cette enveloppe, sérialisée en chaîne JSON, et vous pouvez la renvoyer telle quelle. Les réponses incluent aussi un objet mjml avec les versions de l’enveloppe :

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

Le tableau de bord ouvre un document dans l’éditeur qui l’a enregistré en dernier. Les documents écrits via l’API s’ouvrent dans l’éditeur de code quand format vaut markup, et dans l’éditeur visuel quand il vaut json.

Compiler et enregistrer

Pour les modèles et les campagnes MJML, c’est Emailit qui produit le HTML :

• À la création et à la mise à jour, Emailit valide le MJML et le compile. Le HTML compilé est enregistré comme html du modèle, et tout html que vous envoyez est ignoré.
• L’envoi utilise le HTML enregistré. Les balises Temple y restent, et leur rendu est effectué pour chaque destinataire au moment de l’envoi.
• Mettre à jour uniquement d’autres champs, comme name ou subject, ne déclenche pas de recompilation.
• text n’est pas généré à partir du MJML. Envoyez text vous-même si vous voulez une partie en texte brut.
• Faire passer un modèle existant à editor: "mjml" sans envoyer source compile le source enregistré du modèle, qui doit alors être du MJML.

Le HTML est compilé à l’enregistrement : le HTML d’un modèle existant ne change donc que lorsque le modèle est de nouveau enregistré.

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

Envoyez-le ensuite comme n’importe quel autre modèle avec Envoyer un e-mail : "template": "welcome" et un objet variables.

Validation

Chaque enregistrement exécute les mêmes contrôles que Valider du MJML :

• Syntaxe XML : balises non fermées ou mal appariées et attributs mal formés (xml.*)
• Structure MJML, attributs et valeurs d’attribut pour MJML 5.4.1 (mjml.*)
• Syntaxe Temple et équilibre des blocs {{#if}} (temple.*)
• Le format de la source et les versions (document.*), ainsi que le compilateur lui-même (compiler.*)

Chaque problème détecté est un diagnostic doté d’un niveau de gravité :

Un diagnostic contient ces champs. Les champs qui ne s’appliquent pas sont omis.

Réponse d’erreur

L’enregistrement d’un modèle ou d’une campagne avec des diagnostics d’erreur renvoie 422. Pour cette source :

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

la réponse est :

{
  "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 pour les campagnes) liste jusqu’à cinq messages d’erreur, avec leur ligne quand elle est connue.
• diagnostics liste tous les diagnostics, y compris les avertissements et les informations.
• Une source manquante ou vide renvoie 422 avec "message": "Validation failed", "errors": { "source": ["The source field is required for MJML."] } et un tableau diagnostics vide.

Valider du MJML exécute les mêmes contrôles sans enregistrer et renvoie 200 avec valid: false au lieu de 422.

Codes de diagnostic

XML (sources en balisage)

MJML

Temple

Document et compilateur

Temple dans MJML

Les balises Temple traversent la compilation MJML sans modification. Emailit en effectue le rendu pour chaque destinataire au moment de l’envoi, sur le HTML compilé.

Variables dans le contenu et les attributs

Les variables fonctionnent dans le contenu et dans n’importe quel 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'}}">

• Dans un attribut, écrivez les valeurs par défaut avec des guillemets simples : href="{{url|'https://example.com'}}".
• Le type des valeurs d’attribut qui contiennent du Temple n’est pas vérifié, car la valeur n’est connue qu’au moment de l’envoi. Assurez-vous que la variable contient une valeur valide pour l’attribut, comme une couleur pour background-color.
• Les valeurs sont insérées telles quelles, sans échappement HTML.

Blocs conditionnels

À l’intérieur d’un composant, placez le bloc dans son contenu :

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

Pour afficher ou masquer des composants entiers, placez les balises du bloc dans des éléments <mj-raw> frères :

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

Les balises de bloc isolées entre des composants sont converties en <mj-raw> lors de l’analyse du balisage : ceci revient donc au même :

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

Tout autre texte entre des composants est ignoré par MJML et signalé comme xml.stray-text.

• Les blocs doivent être équilibrés sur l’ensemble du document. Une balise non fermée ou en trop est une erreur.
• Ouvrez et fermez chaque bloc dans le contenu d’un seul composant, ou parmi les éléments <mj-raw> frères d’un même parent. Un bloc qui s’ouvre dans un composant et se ferme dans un autre reçoit un avertissement temple.block-crosses-components, car le masquer couperait la structure HTML.
• Les blocs peuvent être imbriqués.

Non pris en charge

• <mj-include> est rejeté avec mjml.include-not-supported. Collez le MJML inclus dans le document.
• Les balises et les attributs que MJML 5.4.1 ne définit pas sont des erreurs.
• Temple n’a ni boucles, ni helpers, ni partials, ni commentaires, ni triples accolades, ni comparaisons. Consultez Temple.

Variables par canal

Le même modèle MJML peut être envoyé depuis plusieurs endroits, et chacun fournit des variables différentes :

Les éditeurs insèrent les champs personnalisés sous la forme {{cf.<key>}}, qui fonctionne dans les campagnes MJML et dans les automatisations. Pour les envois via l’API, transmettez vous-même les variables.

Pour prévisualiser la version d’un destinataire, appelez Effectuer le rendu de MJML avec variables.

Campagnes

Une campagne avec content_type: "mjml" enregistre son MJML dans content, dans l’un des formats de source, et Emailit compile son html. Comme pour les modèles, tout html que vous envoyez est ignoré. Un MJML invalide renvoie 422 avec errors.content et diagnostics. Envoyer un content vide efface à la fois le contenu et le HTML. Les réponses des campagnes incluent le même objet mjml que les modèles.

Les campagnes MJML effectuent le rendu de l’objet, du HTML et du texte avec Temple pour chaque destinataire, envois de test compris. Ces variables sont disponibles :

Les champs vides du contact comptent comme manquants, et les valeurs par défaut s’appliquent donc : {{first_name|"there"}} donne there pour un contact sans prénom. Gardez un lien {{unsubscribe_url}} dans le pied de page des e-mails marketing.

Les campagnes classiques (HTML, texte et les autres éditeurs) conservent les balises de fusion fixes :

Dans le tableau de bord, créer une campagne à partir d’un modèle MJML copie le document MJML du modèle dans la campagne.

Sans accès à MJML

Pendant l’alpha, Emailit ne compile le MJML des campagnes que pour l’équipe Emailit. Pour tous les autres, y compris les clés API, content_type: "mjml" reste le simple libellé qu’il était avant l’alpha : content est enregistré tel que vous l’envoyez, vous envoyez le HTML compilé dans html, et les envois utilisent les balises de fusion classiques. Créer une campagne à partir d’un modèle MJML copie le HTML du modèle dans une campagne HTML.

Automatisations

L’étape Send email fait référence à un modèle par son ID (tem_…). Les modèles MJML fonctionnent comme les autres : l’étape envoie le HTML compilé du modèle et effectue le rendu de Temple avec les variables de l’automatisation. Consultez E-mails des automatisations.

Dans les paramètres de l’étape, Design a new email crée un modèle MJML à partir d’un design de départ, le sélectionne pour l’étape et l’ouvre dans l’éditeur visuel. Edit email ouvre le modèle MJML sélectionné. Les modifications portent sur le modèle lui-même : chaque étape et chaque appel API qui utilise ce modèle les reçoit donc. Sans accès à MJML, l’étape affiche à la place un lien vers le modèle.

Édition collaborative

Toutes les personnes qui ouvrent le même modèle ou la même campagne MJML enregistrés modifient un même brouillon partagé en temps réel, dans l’un ou l’autre éditeur :

• Présence : l’en-tête indique qui d’autre modifie le document et ce que chacun fait. Dans l’éditeur visuel, vous voyez leurs sélections, leurs curseurs et, là où ils modifient quelque chose, une brève surbrillance de leur couleur. Layers indique qui a sélectionné un composant. Sélectionnez l’avatar d’une personne pour accéder à sa sélection.
• Fusion des modifications : les modifications de composants, d’attributs ou de parties de texte différents se combinent au lieu de s’écraser. Pendant qu’une personne saisit un texte sur le canevas, ce texte est verrouillé pour les autres.
• Éditeur de code : vos modifications sont fusionnées dans le brouillon partagé au fil de la saisie. Les modifications des autres apparaissent dans votre code dès que vous faites une pause dans la saisie, pour que votre curseur ne saute pas. Si votre code contient une erreur de syntaxe, elles attendent que vous la corrigiez.
• Annuler et rétablir n’annulent que vos propres modifications.
• Enregistrement : il n’y a qu’un seul Save pour tout le monde. L’en-tête indique les modifications non enregistrées de l’ensemble du brouillon, et qui a enregistré en dernier. L’envoi utilise toujours la version enregistrée.
• Le brouillon est conservé : fermer l’éditeur ou perdre la connexion ne fait pas perdre les modifications. Elles restent dans le brouillon partagé et se synchronisent quand vous êtes de nouveau en ligne. Rouvrir l’éditeur restaure les modifications non enregistrées, et vous pouvez les abandonner pour revenir à la version enregistrée.
• Enregistré ailleurs : quand le modèle ou la campagne est enregistré en dehors de l’éditeur (l’API, MCP ou Edit with AI) pendant qu’il est ouvert, un brouillon sans modifications non enregistrées passe à la version enregistrée. Un brouillon avec des modifications non enregistrées les conserve et propose Load saved version ou Keep this draft.
• Supprimé : si le modèle ou la campagne est supprimé, ou n’est plus en MJML, pendant que vous le modifiez, l’éditeur vous prévient et vous permet de copier le MJML.

L’édition collaborative nécessite un MJML enregistré et valide. Un modèle ou une campagne dont le MJML ne peut pas être analysé, ou qui n’est pas encore enregistré en MJML, s’ouvre sans elle : chaque personne modifie seule, et le dernier enregistrement l’emporte. L’éditeur l’indique dans une bannière. Dans un espace de travail suspendu, les éditeurs sont en lecture seule.

Versions et mises à niveau

Emailit compile avec une seule version de MJML à la fois, actuellement la 5.4.1. Chaque document enregistré indique la version de MJML qu’il vise (mjml_version), et Emailit la vérifie chaque fois que le document est compilé :

Un document dont le schema_version est plus récent que ce qu’Emailit sait lire est rejeté avec document.unsupported-schema. L’enregistrement stocke le document avec les valeurs actuelles de mjml_version et de schema_version. Vérifiez l’aperçu après une mise à niveau.

Les éditeurs affichent leur version et leur journal des modifications. Quand un document a été enregistré avec une version d’éditeur plus récente que celle de la page que vous avez ouverte, l’éditeur vous demande de recharger la page.

MJML pour les agents IA

Récupérer la référence MJML fournit à vos outils et aux modèles d’IA ce dont ils ont besoin pour écrire du MJML valide pour Emailit : chaque composant avec ses parents, ses enfants et ses attributs autorisés (type et valeur par défaut), le guide Temple, des règles d’écriture et un reference_text compact en texte brut pour les prompts.

Sur le serveur MCP, les sessions de l’équipe Emailit disposent aussi de ces outils dans le groupe d’outils templates :

Quand un enregistrement échoue à la validation, l’erreur de l’outil liste les diagnostics d’erreur et d’avertissement avec leurs numéros de ligne, pour que l’agent puisse corriger la source. Un déroulement type : lire la référence, écrire le MJML, appeler validate-mjml jusqu’à ce que valid vaille true, enregistrer avec create-template, puis vérifier la version d’un destinataire avec render-mjml. Les autres sessions ne voient ni ces outils ni ces paramètres.

Dans le tableau de bord

• Modèles : créez un modèle et choisissez MJML Visual Editor (Alpha) ou MJML Code Editor (Alpha).
• Éditeur visuel : glisser-déposer sur le rendu de l’e-mail, une arborescence de calques, un panneau de propriétés pour chaque attribut MJML, les paramètres du document (head, polices, styles et attributs par défaut), des variables Temple dans n’importe quelle propriété et des blocs conditionnels autour des composants.
• Éditeur de code : autocomplétion des balises, attributs et valeurs MJML et de Temple, validation dans le code avec corrections rapides, et mise en forme.
• Les deux éditeurs : un aperçu en direct sur ordinateur et mobile, compilé dans le navigateur avec MJML 5.4.1, un aperçu avec des données d’exemple (avec rendu de Temple), une liste des problèmes et un assistant IA quand il est activé. Vous pouvez basculer entre Visual et Code sur le même document ; passer en Visual nécessite un code sans erreur de syntaxe. L’enregistrement est bloqué tant que le MJML contient des erreurs.
• Édition collaborative : les collègues qui ouvrent le même modèle ou la même campagne le modifient en temps réel. Consultez Édition collaborative.
• Edit with AI : décrivez une modification d’un modèle ou d’une campagne MJML sans ouvrir l’éditeur.
• Import : un fichier .mjml, un fichier .json en MJML JSON ou en document MJML Emailit, ou un ZIP avec template.mjml et un dossier images/ à la racine.
• Export : MJML (balisage), MJML JSON (le document enregistré), HTML, ou un ZIP avec template.mjml, template.html et images/. L’export fonctionne pour tout le monde.
• Campagnes : choisissez l’éditeur MJML Visual ou Code pour le contenu de la campagne.
• Automatisations : concevez sur place l’e-mail d’une étape Send email. Consultez Automatisations.

Voir aussi

• Créer et modifier des modèles
• Langage de templates Temple
• Référence de l’API MJML
• Importer et exporter