Editores e API de MJML

O MJML é uma linguagem de marcação para e-mails responsivos. Você escreve seções, colunas e componentes como <mj-text> e <mj-button>, e o MJML os compila em um HTML que é renderizado de forma consistente nos clientes de e-mail. No Emailit, o MJML pode ser o código-fonte de um template ou de uma campanha: você o escreve nos editores do painel ou o envia pela API, e o Emailit o valida e compila o HTML.

Visão geral

• Templates: editor: "mjml" com o MJML em source. Consulte Criar um template.
• Campanhas: content_type: "mjml" com o MJML em content. Consulte Campanhas.
• Automações: a etapa Send email envia um template MJML como qualquer outro template. Consulte Automações.
• Endpoints de MJML: Validar MJML, Renderizar MJML e Obter a referência do MJML.

Quem pode usar o MJML

Durante a fase alfa, o MJML está disponível apenas para os administradores da plataforma Emailit. O papel Admin de um workspace não é suficiente.

Todos continuam podendo renomear, publicar, exportar, enviar e excluir templates e campanhas MJML. Duplicar um template MJML cria um novo template MJML, então isso exige acesso ao MJML.

Versão do MJML

O Emailit compila todo o MJML com o MJML 5.4.1, tanto no servidor quanto na prévia ao vivo dos editores. A validação confere tags, atributos e valores de atributos com base nessa versão. Obter a referência do MJML retorna a versão e todos os componentes e atributos que ela suporta.

Editores

O painel tem dois editores MJML. Os dois são versionados e os dois são versões alfa 0.x.

Os dois editores salvam o template com editor: "mjml". O documento armazenado registra qual editor, e qual versão dele, o salvou por último. Os colegas podem editar o mesmo template ou a mesma campanha ao mesmo tempo. Consulte Edição colaborativa.

Formatos do código-fonte

Em todos os lugares em que o Emailit aceita MJML (o source de um template, o content de uma campanha e o campo source dos endpoints de MJML), você pode enviar qualquer um destes formatos:

Qualquer outra coisa é rejeitada com document.unrecognized. Um código-fonte com mais de 2 MB é rejeitado com document.too-large.

O documento armazenado

O Emailit armazena o MJML em um envelope versionado. Ele é o source do template e o content da campanha:

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

O que você envia define o formato: a marcação é armazenada como markup, e o MJML JSON, como json. Os dois são registrados como editor: "api". Um envelope que você envia mantém o editor e o editor_version dele.

As respostas da API retornam source como esse envelope, serializado em uma string JSON, e você pode enviá-lo de volta sem alterações. As respostas também incluem um objeto mjml com as versões do envelope:

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

O painel abre um documento no editor que o salvou por último. Os documentos escritos pela API abrem no Code Editor quando format é markup e no Visual Editor quando é json.

Compilar e salvar

Nos templates e nas campanhas MJML, é o Emailit que gera o HTML:

• Ao criar e ao atualizar, o Emailit valida o MJML e o compila. O HTML compilado é armazenado como o html do template, e qualquer html que você enviar é ignorado.
• O envio usa o HTML armazenado. As tags do Temple continuam nele e são renderizadas para cada destinatário no momento do envio.
• Atualizar apenas outros campos, como name ou subject, não recompila o template.
• text não é gerado a partir do MJML. Envie text você mesmo se quiser uma parte em texto simples.
• Mudar um template existente para editor: "mjml" sem enviar source compila o source armazenado do template, que então precisa ser MJML.

O HTML é compilado quando você salva, então o HTML de um template existente só muda quando ele é salvo de novo.

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

Depois, envie-o como qualquer outro template com Enviar um e-mail: "template": "welcome" e um objeto variables.

Validação

Cada vez que você salva, o Emailit executa as mesmas verificações de Validar MJML:

• Sintaxe XML: tags não fechadas ou que não correspondem e atributos malformados (xml.*)
• Estrutura, atributos e valores de atributos do MJML para o MJML 5.4.1 (mjml.*)
• Sintaxe do Temple e blocos {{#if}} balanceados (temple.*)
• O formato e as versões do código-fonte (document.*), e o próprio compilador (compiler.*)

Cada problema encontrado é um diagnóstico com uma gravidade:

Um diagnóstico tem estes campos. Os campos que não se aplicam ficam de fora.

Resposta de erro

Salvar um template ou uma campanha com diagnósticos de erro retorna 422. Para este código-fonte:

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

a resposta é:

{
  "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 nas campanhas) lista até cinco mensagens de erro, com a linha de cada uma quando ela é conhecida.
• diagnostics lista todos os diagnósticos, incluindo avisos e informações.
• Um código-fonte ausente ou vazio retorna 422 com "message": "Validation failed", "errors": { "source": ["The source field is required for MJML."] } e um array diagnostics vazio.

Validar MJML executa as mesmas verificações sem salvar e retorna 200 com valid: false em vez de 422.

Códigos de diagnóstico

XML (código-fonte em marcação)

MJML

Temple

Documento e compilador

Temple no MJML

As tags do Temple passam pela compilação do MJML sem alterações. O Emailit as renderiza para cada destinatário no momento do envio, sobre o HTML compilado.

Variáveis no conteúdo e nos atributos

As variáveis funcionam no conteúdo e em qualquer 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 um atributo, escreva os valores padrão com aspas simples: href="{{url|'https://example.com'}}".
• Os valores de atributos que contêm Temple não têm o tipo verificado, porque o valor só é conhecido no momento do envio. Garanta que a variável tenha um valor válido para o atributo, como uma cor para background-color.
• Os valores são inseridos como estão, sem escape de HTML.

Blocos condicionais

Dentro de um único componente, coloque o bloco no conteúdo dele:

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

Para mostrar ou ocultar componentes inteiros, coloque as tags do bloco em elementos <mj-raw> irmãos:

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

As tags de bloco soltas entre componentes são convertidas em <mj-raw> quando a marcação é interpretada, então isto é a mesma coisa:

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

Qualquer outro texto entre componentes é ignorado pelo MJML e reportado como xml.stray-text.

• Os blocos precisam estar balanceados no documento inteiro. Uma tag não fechada ou sobrando é um erro.
• Abra e feche cada bloco dentro do conteúdo de um único componente, ou entre os <mj-raw> irmãos de um mesmo elemento pai. Um bloco que abre em um componente e fecha em outro recebe um aviso temple.block-crosses-components, porque ocultá-lo cortaria a estrutura do HTML.
• Os blocos podem ser aninhados.

Sem suporte

• <mj-include> é rejeitado com mjml.include-not-supported. Cole o MJML incluído no documento.
• Tags e atributos que o MJML 5.4.1 não define são erros.
• O Temple não tem loops, helpers, partials, comentários, chaves triplas nem comparações. Consulte Temple.

Variáveis por canal

O mesmo template MJML pode ser enviado de vários lugares, e cada um fornece variáveis diferentes:

Os editores inserem os campos personalizados como {{cf.<key>}}, que funciona nas campanhas MJML e nas automações. Nos envios pela API, passe você mesmo as variáveis.

Para ver a prévia da versão de um destinatário, chame Renderizar MJML com variables.

Campanhas

Uma campanha com content_type: "mjml" armazena o MJML em content, em qualquer um dos formatos do código-fonte, e o Emailit compila o html dela. Como nos templates, qualquer html que você enviar é ignorado. Um MJML inválido retorna 422 com errors.content e diagnostics. Enviar um content vazio limpa tanto o conteúdo quanto o HTML. As respostas de campanhas incluem o mesmo objeto mjml dos templates.

As campanhas MJML renderizam o assunto, o HTML e o texto com o Temple para cada destinatário, inclusive nos envios de teste. Estas variáveis estão disponíveis:

Os campos vazios do contato contam como ausentes, então os valores padrão se aplicam: {{first_name|"there"}} renderiza there para um contato sem nome. Mantenha um link {{unsubscribe_url}} no rodapé dos e-mails de marketing.

As campanhas clássicas (HTML, texto e os outros editores) mantêm as tags de mesclagem fixas:

No painel, iniciar uma campanha a partir de um template MJML copia o documento MJML do template para a campanha.

Sem acesso ao MJML

Durante a fase alfa, o Emailit compila o MJML de campanhas apenas para a equipe do Emailit. Para todos os outros, incluindo as chaves de API, content_type: "mjml" continua sendo o simples rótulo que era antes da fase alfa: content é armazenado como você o envia, você envia o HTML compilado em html e os envios usam as tags de mesclagem clássicas. Iniciar uma campanha a partir de um template MJML copia o HTML do template para uma campanha HTML.

Automações

A etapa Send email faz referência a um template pelo ID (tem_…). Os templates MJML funcionam como qualquer outro: a etapa envia o HTML compilado do template e renderiza o Temple com as variáveis da automação. Consulte E-mails de automações.

Nas configurações da etapa, Design a new email cria um template MJML a partir de um design inicial, seleciona-o para a etapa e o abre no Visual Editor. Edit email abre o template MJML selecionado. As edições alteram o próprio template, então todas as etapas e chamadas à API que usam o template as recebem. Sem acesso ao MJML, a etapa mostra um link para o template.

Edição colaborativa

Todos que abrem o mesmo template ou a mesma campanha MJML salvos editam um único rascunho compartilhado em tempo real, em qualquer um dos editores:

• Presença: a barra superior mostra quem mais está editando e o que cada pessoa está fazendo. No Visual Editor, você vê as seleções e os cursores dos outros e um breve destaque na cor de cada um onde eles alteram algo. Layers mostra quem selecionou um componente. Selecione o avatar de alguém para ir até a seleção dessa pessoa.
• As edições são mescladas: alterações em componentes, atributos ou partes diferentes de um texto se combinam em vez de sobrescrever umas às outras. Enquanto alguém digita em um texto no canvas, esse texto fica bloqueado para os outros.
• Code Editor: as suas alterações são mescladas no rascunho compartilhado enquanto você digita. As alterações dos outros aparecem no seu código quando você para de digitar, para que o cursor não salte. Se o seu código tiver um erro de sintaxe, elas esperam até você corrigi-lo.
• Desfazer e refazer desfazem apenas as suas próprias alterações.
• Salvar: há um único Save para todos. A barra superior mostra as alterações não salvas do rascunho inteiro e quem salvou por último. O envio sempre usa a versão salva.
• O rascunho é mantido: fechar o editor ou perder a conexão não faz você perder as alterações. Elas ficam no rascunho compartilhado e são sincronizadas quando você volta a ficar on-line. Reabrir o editor restaura as alterações não salvas, e você pode descartá-las para voltar à versão salva.
• Salvo em outro lugar: quando o template ou a campanha é salvo fora do editor (pela API, pelo MCP ou pelo Edit with AI) enquanto está aberto, um rascunho sem alterações não salvas passa para a versão salva. Um rascunho com alterações não salvas as mantém e oferece Load saved version ou Keep this draft.
• Excluído: se o template ou a campanha for excluído, ou deixar de ser MJML, enquanto você edita, o editor avisa e permite copiar o MJML.

A edição colaborativa exige MJML salvo e válido. Os templates e as campanhas cujo MJML não pode ser interpretado, ou que ainda não foram salvos como MJML, abrem sem ela: cada pessoa edita sozinha e o último salvamento prevalece. O editor avisa isso em um banner. Em um workspace suspenso, os editores ficam somente leitura.

Versões e atualizações

O Emailit compila com uma versão do MJML por vez, atualmente a 5.4.1. Cada documento armazenado registra o mjml_version ao qual se destina, e o Emailit o verifica sempre que o documento é compilado:

Um documento cujo schema_version é mais novo do que o Emailit consegue ler é rejeitado com document.unsupported-schema. Ao salvar, o documento é armazenado com o mjml_version e o schema_version atuais. Confira a prévia depois de uma atualização.

Os editores mostram a versão e o changelog deles. Quando um documento foi salvo com uma versão do editor mais nova do que a da página que você tem aberta, o editor pede que você recarregue a página.

MJML para agentes de IA

Obter a referência do MJML dá às ferramentas de desenvolvimento e aos modelos de IA o que eles precisam para escrever MJML válido para o Emailit: todos os componentes, com os elementos pais, os filhos e os atributos permitidos (tipo e valor padrão), o guia do Temple, as regras de escrita e um reference_text compacto em texto simples para prompts.

No servidor MCP, as sessões da equipe do Emailit também recebem estas ferramentas no toolset templates:

Quando um salvamento falha na validação, o erro da ferramenta lista os diagnósticos de erro e de aviso com os números de linha, para que o agente possa corrigir o código-fonte. Um fluxo típico: ler a referência, escrever o MJML, chamar validate-mjml até que valid seja true, salvar com create-template e depois conferir a versão de um destinatário com render-mjml. As outras sessões não veem essas ferramentas nem esses parâmetros.

No painel

• Templates: crie um template e escolha MJML Visual Editor (Alpha) ou MJML Code Editor (Alpha).
• Visual Editor: arrastar e soltar sobre o e-mail renderizado, uma árvore de camadas, um painel de propriedades para cada atributo do MJML, configurações do documento (head, fontes, estilos e atributos padrão), variáveis do Temple em qualquer propriedade e blocos condicionais em volta de componentes.
• Code Editor: preenchimento automático para tags, atributos e valores do MJML e para o Temple, validação inline com correções rápidas e formatação.
• Os dois editores: uma prévia ao vivo para desktop e celular, compilada no navegador com o MJML 5.4.1, uma prévia com dados de exemplo (com o Temple renderizado), uma lista de problemas e um assistente de IA, quando ele está ativado. Você pode alternar entre Visual e Code no mesmo documento; para mudar para Visual, o código não pode ter erros de sintaxe. Não é possível salvar enquanto o MJML tiver erros.
• Edição colaborativa: os colegas que abrem o mesmo template ou a mesma campanha editam juntos em tempo real. Consulte Edição colaborativa.
• Edit with AI: descreva uma alteração em um template ou em uma campanha MJML sem abrir o editor.
• Importação: um arquivo .mjml, um arquivo .json com MJML JSON ou com um documento MJML do Emailit, ou um ZIP com template.mjml e uma pasta images/ na raiz.
• Exportação: MJML (marcação), MJML JSON (o documento armazenado), HTML ou um ZIP com template.mjml, template.html e images/. A exportação funciona para todos.
• Campanhas: escolha o MJML Visual Editor ou o MJML Code Editor para o conteúdo da campanha.
• Automações: crie o e-mail de uma etapa Send email ali mesmo. Consulte Automações.

Veja também

• Criar e editar templates
• Linguagem de templates Temple
• Referência da API de MJML
• Importar e exportar