Aller au contenu
Docs

MJML (alpha)

Validez du MJML, effectuez-en le rendu et consultez la référence MJML. En alpha, réservé à l’équipe Emailit.

URL de basehttps://api.emailit.com/v2AuthentificationErreursLimites de débit

Valider du MJML

Vérifie du MJML comme le fait l’enregistrement d’un modèle (syntaxe XML, structure MJML, types d’attribut et syntaxe Temple) et le compile avec MJML 5.4.1. Rien n’est enregistré. Un MJML invalide renvoie quand même 200, avec valid: false et les diagnostics. Nécessite la portée full.

Pour le détail de chaque contrôle, consultez Validation.

POST/mjml/validate

Paramètres du corps

sourcestring | objectObligatoire

Le MJML à vérifier : du balisage MJML (<mjml>…</mjml>), du MJML JSON ou un document MJML Emailit, comme le source enregistré d’un modèle. Consultez Formats de source. 2 Mo au maximum.

Réponse

Renvoie 200 OK avec le résultat, même quand le MJML est invalide :

Champ Type Description
valid boolean true quand il n’y a aucun diagnostic d’erreur : un modèle avec cette source peut donc être enregistré.
mjml_version string La version de MJML avec laquelle Emailit compile.
format string ou null La façon dont la source a été lue : markup ou json. null quand elle n’a pas pu être lue.
diagnostics array Tous les diagnostics d’erreur, d’avertissement et d’information.

valid: true signifie qu’un modèle avec cette source serait accepté. Corrigez aussi les avertissements : ils signalent généralement de vrais problèmes, comme une balise <mj-title> manquante. Pour obtenir le HTML, utilisez Effectuer le rendu de MJML.

Renvoie 422 avec message: "Validation failed" quand source est absent ou vide, et 403 avec error: "mjml_alpha" sans accès à MJML.

Objet diagnostic

Les champs qui ne s’appliquent pas sont omis.

Champ Type Description
severity string error, warning ou info. Seules les erreurs rendent valid faux.
code string Un code stable, par exemple mjml.invalid-child, xml.unclosed-tag ou temple.unclosed-if. Voir Codes de diagnostic.
message string Une explication lisible.
line integer Ligne dans le balisage, à partir de 1. Sources en balisage uniquement.
column integer Colonne dans le balisage, à partir de 1. Sources en balisage uniquement.
tag string L’élément concerné par le diagnostic.
attribute string L’attribut concerné par le diagnostic.
path integer[] Chemin d’indices d’enfants depuis la racine <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": []
    }
  ]
}

Effectuer le rendu de MJML

Compile du MJML en HTML tel qu’Emailit l’envoie, avec MJML 5.4.1. Avec variables, la réponse inclut aussi rendered_html : le HTML après application de Temple, tel qu’un destinataire le recevrait. Rien n’est enregistré ni envoyé. Nécessite la portée full.

Cet endpoint est limité à 120 requêtes par minute.

POST/mjml/render

Paramètres du corps

sourcestring | objectObligatoire

Le MJML à compiler : du balisage MJML (<mjml>…</mjml>), du MJML JSON ou un document MJML Emailit, comme le source enregistré d’un modèle. Consultez Formats de source. 2 Mo au maximum.

variablesobject

Variables Temple pour rendered_html, comme first_name, ou un objet cf avec les champs personnalisés de campagne. Rien n’est rempli automatiquement : transmettez les variables que le canal d’envoi fournirait. Consultez Variables par canal. Doit être un objet ; toute autre valeur renvoie 400.

Réponse

Renvoie 200 OK avec le résultat, même quand le MJML est invalide :

Champ Type Description
valid boolean true quand il n’y a aucun diagnostic d’erreur.
mjml_version string La version de MJML avec laquelle Emailit compile.
html string ou null Le HTML compilé, avec les balises Temple laissées en place, tel qu’Emailit l’enregistre pour un modèle. null quand le MJML contient des erreurs.
html_bytes integer Taille de html en UTF-8. Gmail tronque les messages de plus de 102 Ko environ. 0 quand html vaut null.
diagnostics array Tous les diagnostics d’erreur, d’avertissement et d’information. Voir Valider du MJML.
rendered_html string ou null html avec les variables appliquées par Temple. Présent uniquement si vous envoyez variables, et null quand le MJML contient des erreurs.

Un MJML invalide renvoie 200 avec valid: false, html: null et les diagnostics. rendered_html utilise exactement les variables que vous envoyez : les variables manquantes donnent une chaîne vide ou leur valeur par défaut, si bien que {{first_name|"there"}} donne there. Le texte brut n’est pas généré à partir du MJML.

Renvoie 422 avec message: "Validation failed" quand source est absent ou vide, 400 quand variables n’est pas un objet, et 403 avec error: "mjml_alpha" sans accès à MJML.

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

Récupérer la référence MJML

Récupère chaque composant et chaque attribut de la version de MJML avec laquelle Emailit compile, les versions actuelles des éditeurs, le guide Temple et les règles d’écriture. Utilisez-la pour créer des outils ou pour fournir à un modèle d’IA ce dont il a besoin pour écrire des modèles MJML valides. Nécessite la portée full.

La même référence est disponible pour les agents IA sous la forme de l’outil MCP get-mjml-reference. Consultez MJML pour les agents IA.

GET/mjml/reference

Réponse

Renvoie 200 OK avec la référence. L’exemple ci-dessus est abrégé : components liste les 36 composants avec tous leurs attributs.

Champ Type Description
mjml_version string La version de MJML avec laquelle Emailit compile.
document_schema_version integer Le schema_version actuel du document MJML enregistré.
editors object La version actuelle et le stade (alpha, beta ou stable) de mjml-code et de mjml-visual.
components array Tous les composants MJML. Voir ci-dessous.
temple_guide string Le fonctionnement de Temple dans MJML : variables, valeurs par défaut, conditions et variables de campagne.
rules string Les règles d’écriture du MJML : structure, attributs autorisés et accessibilité.
reference_text string Toute la référence des composants sous forme de texte brut compact, pour les prompts.

Renvoie 403 avec error: "mjml_alpha" sans accès à MJML.

Objet composant

Champ Type Description
tag string Nom de la balise, par exemple mj-button.
label string Nom affiché.
description string Ce que fait le composant.
category string root, head, layout, content, interactive, child ou advanced.
ending_tag boolean true quand le contenu est du HTML brut ou du texte (mj-text, mj-button, mj-raw, …).
parents string[] Les éléments dans lesquels ce composant peut être placé.
children string[] Les éléments que ce composant peut contenir. ["*"] signifie n’importe quel composant (mj-attributes).
attributes array Les attributs, chacun avec name, type (un type MJML comme color, unit(px,%){1,4} ou enum(left,center,right)) et default (null s’il n’y en a pas).
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]. …"
}

Cette page vous a-t-elle été utile ?

Merci pour votre retour.

Merci, nous lisons chaque message.

Esc

Populaires

↑↓pour naviguer↵pour ouvrirEscpour fermer