Vai al contenuto
Docs

MJML (alpha)

Convalida ed elabora l’MJML e consulta il riferimento MJML. In alpha, aperto solo al team di Emailit.

URL di basehttps://api.emailit.com/v2AutenticazioneErroriLimiti di frequenza

Convalida l’MJML

Controlla l’MJML come fa il salvataggio di un template (sintassi XML, struttura MJML, tipi degli attributi e sintassi Temple) e lo compila con MJML 5.4.1. Non viene salvato nulla. Anche un MJML non valido restituisce 200, con valid: false e le diagnostiche. Richiede il permesso full.

Per sapere cosa copre ogni controllo, vedi Convalida.

POST/mjml/validate

Parametri del corpo

sourcestring | objectObbligatorio

L’MJML da controllare: markup MJML (<mjml>…</mjml>), MJML JSON o un documento MJML di Emailit, come il source memorizzato di un template. Vedi Formati del sorgente. Massimo 2 MB.

Restituisce

Restituisce 200 OK con il risultato, anche quando l’MJML non è valido:

Campo Tipo Descrizione
valid boolean true quando non ci sono diagnostiche di errore, quindi un template con questo sorgente si può salvare.
mjml_version string La versione di MJML con cui Emailit compila.
format string o null Come è stato letto il sorgente: markup o json. null quando non è stato possibile leggerlo.
diagnostics array Tutte le diagnostiche: errori, avvisi e informazioni.

valid: true significa che un template con questo sorgente verrebbe accettato. Correggi anche gli avvisi: di solito indicano problemi reali, come un <mj-title> mancante. Per ottenere l’HTML, usa Elabora l’MJML.

Restituisce 422 con message: "Validation failed" quando source manca o è vuoto, e 403 con error: "mjml_alpha" senza accesso a MJML.

Oggetto diagnostica

I campi che non si applicano vengono omessi.

Campo Tipo Descrizione
severity string error, warning o info. Solo gli errori rendono falso valid.
code string Un codice stabile, ad esempio mjml.invalid-child, xml.unclosed-tag o temple.unclosed-if. Vedi Codici delle diagnostiche.
message string Una spiegazione leggibile.
line integer Riga nel markup, a partire da 1. Solo per i sorgenti in markup.
column integer Colonna nel markup, a partire da 1. Solo per i sorgenti in markup.
tag string L’elemento a cui si riferisce la diagnostica.
attribute string L’attributo a cui si riferisce la diagnostica.
path integer[] Percorso di indici dei figli a partire dalla radice <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": []
    }
  ]
}

Elabora l’MJML

Compila l’MJML nell’HTML che Emailit invia, con MJML 5.4.1. Con variables, la risposta include anche rendered_html: l’HTML dopo l’elaborazione di Temple, come lo riceverebbe un destinatario. Non viene salvato né inviato nulla. Richiede il permesso full.

Questo endpoint è limitato a 120 richieste al minuto.

POST/mjml/render

Parametri del corpo

sourcestring | objectObbligatorio

L’MJML da compilare: markup MJML (<mjml>…</mjml>), MJML JSON o un documento MJML di Emailit, come il source memorizzato di un template. Vedi Formati del sorgente. Massimo 2 MB.

variablesobject

Variabili Temple per rendered_html, come first_name, o un oggetto cf con i campi personalizzati delle campagne. Nulla viene inserito automaticamente: passa le variabili che fornirebbe il canale di invio. Vedi Variabili per canale. Deve essere un oggetto; qualsiasi altro valore restituisce 400.

Restituisce

Restituisce 200 OK con il risultato, anche quando l’MJML non è valido:

Campo Tipo Descrizione
valid boolean true quando non ci sono diagnostiche di errore.
mjml_version string La versione di MJML con cui Emailit compila.
html string o null L’HTML compilato, con i tag Temple ancora al loro posto, così come Emailit lo memorizza per un template. null quando l’MJML ha errori.
html_bytes integer Dimensione di html in UTF-8. Gmail tronca i messaggi oltre circa 102 KB. 0 quando html è null.
diagnostics array Tutte le diagnostiche: errori, avvisi e informazioni. Vedi Convalida l’MJML.
rendered_html string o null html con le variables applicate da Temple. Presente solo se invii variables, e null quando l’MJML ha errori.

Un MJML non valido restituisce 200 con valid: false, html: null e le diagnostiche. rendered_html usa esattamente le variables che invii: le variabili mancanti diventano stringhe vuote o il loro valore predefinito, quindi {{first_name|"there"}} diventa there. Il testo semplice non viene generato dall’MJML.

Restituisce 422 con message: "Validation failed" quando source manca o è vuoto, 400 quando variables non è un oggetto, e 403 con error: "mjml_alpha" senza accesso a 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"
}

Recupera il riferimento MJML

Recupera tutti i componenti e gli attributi MJML della versione di MJML con cui Emailit compila, le versioni attuali degli editor, la guida a Temple e le regole di scrittura. Usalo per creare strumenti di sviluppo o per dare a un modello AI ciò che gli serve per scrivere template MJML validi. Richiede il permesso full.

Lo stesso riferimento è disponibile per gli agenti AI come strumento MCP get-mjml-reference. Vedi MJML per gli agenti AI.

GET/mjml/reference

Restituisce

Restituisce 200 OK con il riferimento. L’esempio qui sopra è abbreviato: components elenca tutti i 36 componenti con tutti i loro attributi.

Campo Tipo Descrizione
mjml_version string La versione di MJML con cui Emailit compila.
document_schema_version integer Il valore attuale di schema_version del documento MJML memorizzato.
editors object La versione attuale e la fase (alpha, beta o stable) di mjml-code e mjml-visual.
components array Tutti i componenti MJML. Vedi sotto.
temple_guide string Come funziona Temple dentro MJML: variabili, valori predefiniti, condizioni e variabili delle campagne.
rules string Regole di scrittura MJML: struttura, attributi consentiti e accessibilità.
reference_text string L’intero riferimento dei componenti in testo semplice compatto, per i prompt.

Restituisce 403 con error: "mjml_alpha" senza accesso a MJML.

Oggetto componente

Campo Tipo Descrizione
tag string Nome del tag, ad esempio mj-button.
label string Nome visualizzato.
description string Cosa fa il componente.
category string root, head, layout, content, interactive, child o advanced.
ending_tag boolean true quando il contenuto è HTML grezzo o testo (mj-text, mj-button, mj-raw, …).
parents string[] Elementi in cui si può inserire questo componente.
children string[] Elementi che questo componente può contenere. ["*"] indica qualsiasi componente (mj-attributes).
attributes array Attributi, ognuno con name, type (un tipo MJML come color, unit(px,%){1,4} o enum(left,center,right)) e default (null quando non c’è).
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]. …"
}

Questa pagina ti è stata utile?

Grazie del feedback.

Grazie, leggiamo ogni messaggio.

Esc

Popolari

↑↓per spostarti↵per aprireEscper chiudere