Editores y API de MJML

MJML es un lenguaje de marcado para emails adaptables. Escribes secciones, columnas y componentes como <mj-text> y <mj-button>, y MJML los compila en un HTML que se muestra de forma coherente en todos los clientes de correo. En Emailit, MJML puede ser el origen de una plantilla o de una campaña: lo escribes en los editores del panel o lo envías con la API, y Emailit lo valida y compila el HTML.

Descripción general

• Plantillas: editor: "mjml" con el MJML en source. Consulta Crear una plantilla.
• Campañas: content_type: "mjml" con el MJML en content. Consulta Campañas.
• Automatizaciones: el paso Send email envía una plantilla MJML como cualquier otra plantilla. Consulta Automatizaciones.
• Endpoints de MJML: Validar MJML, Renderizar MJML y Obtener la referencia de MJML.

Quién puede usar MJML

Durante la fase alfa, MJML solo está disponible para los administradores de la plataforma de Emailit. El rol Admin de un espacio de trabajo no basta.

Cualquiera puede seguir cambiando el nombre de las plantillas y campañas MJML, publicándolas, exportándolas, enviándolas y eliminándolas. Duplicar una plantilla MJML crea una plantilla MJML nueva, así que requiere acceso a MJML.

Versión de MJML

Emailit compila todo el MJML con MJML 5.4.1, tanto en el servidor como en la vista previa en directo de los editores. La validación comprueba las etiquetas, los atributos y los valores de los atributos según esa versión. Obtener la referencia de MJML devuelve la versión y todos los componentes y atributos que admite.

Editores

El panel tiene dos editores MJML. Los dos tienen versiones y los dos son versiones alfa 0.x.

Los dos editores guardan la plantilla con editor: "mjml". El documento guardado registra qué editor, y qué versión de ese editor, lo guardó por última vez. Varios compañeros pueden editar la misma plantilla o campaña a la vez. Consulta Edición conjunta.

Formatos de origen

Allí donde Emailit acepta MJML (el source de una plantilla, el content de una campaña y el campo source de los endpoints de MJML), puedes enviar cualquiera de estos formatos:

Cualquier otra cosa se rechaza con document.unrecognized. Un origen de más de 2 MB se rechaza con document.too-large.

El documento guardado

Emailit guarda el MJML en un envoltorio con versiones. Es el source de la plantilla y el content de la campaña:

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

Lo que envías decide el formato: el marcado se guarda como markup y el MJML JSON como json. Los dos se registran como editor: "api". Un envoltorio que envíes conserva su editor y su editor_version.

Las respuestas de la API devuelven source como este envoltorio, serializado como cadena JSON, y puedes volver a enviarlo sin cambios. Las respuestas también incluyen un objeto mjml con las versiones del envoltorio:

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

El panel abre un documento en el editor que lo guardó por última vez. Los documentos escritos con la API se abren en el Code Editor cuando format es markup y en el Visual Editor cuando es json.

Compilar y guardar

En las plantillas y campañas MJML, Emailit se encarga del HTML:

• Al crear y al actualizar, Emailit valida el MJML y lo compila. El HTML compilado se guarda como el html de la plantilla, y se ignora cualquier html que envíes.
• Los envíos usan el HTML guardado. Las etiquetas de Temple se quedan en él y se renderizan para cada destinatario en el momento del envío.
• Actualizar solo otros campos, como name o subject, no vuelve a compilar.
• text no se genera a partir del MJML. Envía tú text si quieres una parte de texto plano.
• Cambiar una plantilla existente a editor: "mjml" sin enviar source compila el source guardado de la plantilla, que entonces debe ser MJML.

El HTML se compila al guardar, así que el HTML de una plantilla existente solo cambia cuando se vuelve a guardar.

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

Después, envíala como cualquier otra plantilla con Enviar un email: "template": "welcome" y un objeto variables.

Validación

Cada guardado ejecuta las mismas comprobaciones que Validar MJML:

• La sintaxis XML: etiquetas sin cerrar o mal emparejadas y atributos mal formados (xml.*)
• La estructura, los atributos y los valores de los atributos de MJML para MJML 5.4.1 (mjml.*)
• La sintaxis de Temple y que los bloques {{#if}} estén equilibrados (temple.*)
• El formato y las versiones del origen (document.*), y el propio compilador (compiler.*)

Cada hallazgo es un diagnóstico con una gravedad:

Un diagnóstico tiene estos campos. Los campos que no aplican se omiten.

Respuesta de error

Guardar una plantilla o campaña con diagnósticos de error devuelve 422. Con este origen:

<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 respuesta es:

{
  "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 en las campañas) muestra hasta cinco mensajes de error, con su línea cuando se conoce.
• diagnostics muestra todos los diagnósticos, incluidos los de advertencia y los informativos.
• Un origen ausente o vacío devuelve 422 con "message": "Validation failed", "errors": { "source": ["The source field is required for MJML."] } y un array diagnostics vacío.

Validar MJML ejecuta las mismas comprobaciones sin guardar y devuelve 200 con valid: false en lugar de 422.

Códigos de diagnóstico

XML (orígenes de marcado)

MJML

Temple

Documento y compilador

Temple en MJML

Las etiquetas de Temple pasan sin cambios por la compilación de MJML. Emailit las renderiza para cada destinatario en el momento del envío, sobre el HTML compilado.

Variables en el contenido y en los atributos

Las variables funcionan en el contenido y en cualquier atributo:

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

• Dentro de un atributo, escribe los valores por defecto con comillas simples: href="{{url|'https://example.com'}}".
• Los valores de atributo que contienen Temple no se comprueban por tipo, porque el valor solo se conoce en el momento del envío. Asegúrate de que la variable contiene un valor válido para el atributo, como un color para background-color.
• Los valores se insertan tal cual, sin escape HTML.

Bloques condicionales

Dentro de un componente, pon el bloque en su contenido:

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

Para mostrar u ocultar componentes enteros, pon las etiquetas del bloque en elementos <mj-raw> hermanos:

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

Las etiquetas de bloque sueltas entre componentes se convierten en <mj-raw> al analizar el marcado, así que esto es lo mismo:

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

MJML ignora cualquier otro texto entre componentes, que se notifica como xml.stray-text.

• Los bloques deben estar equilibrados en todo el documento. Una etiqueta sin cerrar o sobrante es un error.
• Abre y cierra cada bloque dentro del contenido de un mismo componente, o entre los <mj-raw> hermanos de un mismo padre. Un bloque que se abre en un componente y se cierra en otro recibe una advertencia temple.block-crosses-components, porque ocultarlo cortaría la estructura HTML.
• Los bloques se pueden anidar.

Lo que no se admite

• <mj-include> se rechaza con mjml.include-not-supported. Pega el MJML incluido en el documento.
• Las etiquetas y los atributos que MJML 5.4.1 no define son errores.
• Temple no tiene bucles, helpers, parciales, comentarios, llaves triples ni comparaciones. Consulta Temple.

Variables por canal

La misma plantilla MJML se puede enviar desde varios sitios, y cada uno aporta variables distintas:

Los editores insertan los campos personalizados como {{cf.<key>}}, que funciona en las campañas MJML y en las automatizaciones. En los envíos por API, pasa tú las variables.

Para previsualizar la versión de un destinatario, llama a Renderizar MJML con variables.

Campañas

Una campaña con content_type: "mjml" guarda su MJML en content, en cualquiera de los formatos de origen, y Emailit compila su html. Como en las plantillas, se ignora cualquier html que envíes. Un MJML no válido devuelve 422 con errors.content y diagnostics. Enviar un content vacío borra tanto el contenido como el HTML. Las respuestas de campañas incluyen el mismo objeto mjml que las de plantillas.

Las campañas MJML renderizan el asunto, el HTML y el texto con Temple para cada destinatario, también en los envíos de prueba. Están disponibles estas variables:

Los campos vacíos del contacto cuentan como ausentes, así que se aplican los valores por defecto: {{first_name|"there"}} se renderiza como there para un contacto sin nombre. Mantén un enlace {{unsubscribe_url}} en el pie de los emails de marketing.

Las campañas clásicas (HTML, texto y los demás editores) mantienen las etiquetas de combinación fijas:

En el panel, crear una campaña a partir de una plantilla MJML copia el documento MJML de la plantilla en la campaña.

Sin acceso a MJML

Durante la fase alfa, Emailit solo compila el MJML de las campañas para el equipo de Emailit. Para todos los demás, incluidas las claves de API, content_type: "mjml" sigue siendo la simple etiqueta que era antes de la fase alfa: content se guarda tal como lo envías, tú envías el HTML compilado en html y los envíos usan las etiquetas de combinación clásicas. Crear una campaña a partir de una plantilla MJML copia el HTML de la plantilla en una campaña HTML.

Automatizaciones

El paso Send email hace referencia a una plantilla por su ID (tem_…). Las plantillas MJML funcionan como cualquier otra: el paso envía el HTML compilado de la plantilla y renderiza Temple con las variables de la automatización. Consulta Emails de las automatizaciones.

En la configuración del paso, Design a new email crea una plantilla MJML a partir de un diseño inicial, la selecciona para el paso y la abre en el Visual Editor. Edit email abre la plantilla MJML seleccionada. Los cambios modifican la propia plantilla, así que todos los pasos y las llamadas a la API que usan la plantilla los reciben. Sin acceso a MJML, el paso muestra en su lugar un enlace a la plantilla.

Edición conjunta

Todas las personas que abren la misma plantilla o campaña MJML guardada editan un único borrador compartido en tiempo real, en cualquiera de los dos editores:

• Presencia: el encabezado muestra quién más está editando y qué está haciendo. En el Visual Editor ves sus selecciones, sus cursores y un breve resaltado de su color allí donde cambian algo. Layers muestra quién tiene seleccionado un componente. Selecciona el avatar de alguien para ir a su selección.
• Los cambios se combinan: los cambios en componentes, atributos o partes de un texto distintos se combinan en lugar de sobrescribirse. Mientras alguien escribe en un texto del lienzo, ese texto queda bloqueado para los demás.
• Code Editor: tus cambios se incorporan al borrador compartido mientras escribes. Los cambios de los demás aparecen en tu código cuando dejas de escribir, para que el cursor no salte. Si tu código tiene un error de sintaxis, esperan hasta que lo corrijas.
• Deshacer y rehacer solo deshacen tus propios cambios.
• Guardar: hay un único Save para todos. El encabezado muestra los cambios sin guardar de todo el borrador y quién guardó por última vez. Los envíos siempre usan la versión guardada.
• El borrador se conserva: cerrar el editor o perder la conexión no hace perder cambios. Se quedan en el borrador compartido y se sincronizan cuando vuelves a estar en línea. Al volver a abrir el editor se restauran los cambios sin guardar, y puedes descartarlos para volver a la versión guardada.
• Guardado desde otro sitio: cuando la plantilla o campaña se guarda fuera del editor (con la API, MCP o Edit with AI) mientras está abierta, un borrador que no tiene cambios sin guardar pasa a la versión guardada. Un borrador con cambios sin guardar los conserva y ofrece Load saved version o Keep this draft.
• Eliminada: si la plantilla o campaña se elimina, o deja de ser MJML, mientras editas, el editor te avisa y te permite copiar el MJML.

La edición conjunta requiere un MJML guardado y válido. Una plantilla o campaña cuyo MJML no se puede analizar, o que todavía no se ha guardado como MJML, se abre sin ella: cada persona edita por su cuenta y gana el último guardado. El editor lo indica en un aviso. En un espacio de trabajo suspendido, los editores son de solo lectura.

Versiones y actualizaciones

Emailit compila con una sola versión de MJML a la vez, actualmente la 5.4.1. Cada documento guardado registra la mjml_version para la que está escrito, y Emailit la comprueba siempre que compila el documento:

Un documento cuyo schema_version es más reciente que el que lee Emailit se rechaza con document.unsupported-schema. Al guardar, el documento se guarda con la mjml_version y el schema_version actuales. Comprueba la vista previa después de una actualización.

Los editores muestran su versión y su registro de cambios. Cuando un documento se guardó con una versión del editor más reciente que la de la página que tienes abierta, el editor te pide que la recargues.

MJML para agentes de IA

Obtener la referencia de MJML da a las herramientas de desarrollo y a los modelos de IA lo que necesitan para escribir MJML válido para Emailit: cada componente con sus padres, hijos y atributos permitidos (tipo y valor por defecto), la guía de Temple, las reglas de escritura y un reference_text compacto en texto plano para los prompts.

En el servidor MCP, las sesiones del equipo de Emailit también reciben estas herramientas en el conjunto de herramientas templates:

Cuando un guardado no supera la validación, el error de la herramienta muestra los diagnósticos de error y de advertencia con sus números de línea, para que el agente pueda corregir el origen. Un flujo típico: leer la referencia, escribir el MJML, llamar a validate-mjml hasta que valid sea true, guardar con create-template y después comprobar la versión de un destinatario con render-mjml. Las demás sesiones no ven estas herramientas ni estos parámetros.

En el panel

• Plantillas: crea una plantilla y elige MJML Visual Editor (Alpha) o MJML Code Editor (Alpha).
• Visual Editor: arrastrar y soltar sobre el email renderizado, un árbol de capas, un panel de propiedades para cada atributo de MJML, la configuración del documento (head, fuentes, estilos y atributos por defecto), variables de Temple en cualquier propiedad y bloques condicionales alrededor de los componentes.
• Code Editor: autocompletado de etiquetas, atributos y valores de MJML y de Temple, validación en línea con correcciones rápidas, y formateo.
• Ambos editores: una vista previa en directo para escritorio y móvil compilada en el navegador con MJML 5.4.1, una vista previa con datos de ejemplo (con Temple renderizado), una lista de problemas y un asistente de IA cuando está activado. Puedes cambiar entre Visual y Code en el mismo documento; para pasar a Visual, el código no debe tener errores de sintaxis. No se puede guardar mientras el MJML tenga errores.
• Edición conjunta: los compañeros que abren la misma plantilla o campaña la editan en tiempo real. Consulta Edición conjunta.
• Edit with AI: describe un cambio en una plantilla o campaña MJML sin abrir el editor.
• Importar: un archivo .mjml, un archivo .json de MJML JSON o de documento MJML de Emailit, o un ZIP con template.mjml y una carpeta images/ en la raíz.
• Exportar: MJML (marcado), MJML JSON (el documento guardado), HTML o un ZIP con template.mjml, template.html y images/. La exportación funciona para todos.
• Campañas: elige el MJML Visual Editor o el MJML Code Editor para el contenido de la campaña.
• Automatizaciones: diseña el email de un paso Send email sin salir de él. Consulta Automatizaciones.

Ver también

• Crear y editar plantillas
• Lenguaje de plantillas Temple
• Referencia de la API de MJML
• Importar y exportar