Pular para o conteúdo
Docs

MJML (alfa)

Valide e renderize MJML e consulte a referência do MJML. Em alfa, aberto apenas à equipe do Emailit.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

Validar MJML

Verifica o MJML como acontece ao salvar um template (sintaxe XML, estrutura do MJML, tipos de atributos e sintaxe do Temple) e o compila com o MJML 5.4.1. Nada é salvo. Um MJML inválido também retorna 200, com valid: false e os diagnósticos. Requer uma chave de API com escopo full.

Consulte Validação para ver o que cada verificação cobre.

POST/mjml/validate

Parâmetros do corpo

sourcestring | objectObrigatório

O MJML a verificar: marcação MJML (<mjml>…</mjml>), MJML JSON ou um documento MJML do Emailit, como o source armazenado de um template. Consulte Formatos do código-fonte. Máximo de 2 MB.

Retorno

Retorna 200 OK com o resultado, mesmo quando o MJML é inválido:

Campo Tipo Descrição
valid boolean true quando não há diagnósticos de erro, ou seja, um template com este código-fonte pode ser salvo.
mjml_version string A versão do MJML com que o Emailit compila.
format string ou null Como o código-fonte foi lido: markup ou json. null quando não foi possível lê-lo.
diagnostics array Todos os diagnósticos de erro, de aviso e de informação.

valid: true significa que um template com este código-fonte seria aceito. Corrija também os avisos: eles costumam apontar problemas reais, como a falta de um <mj-title>. Para obter o HTML, use Renderizar MJML.

Retorna 422 com message: "Validation failed" quando source está ausente ou em branco, e 403 com error: "mjml_alpha" sem acesso ao MJML.

Objeto de diagnóstico

Os campos que não se aplicam ficam de fora.

Campo Tipo Descrição
severity string error, warning ou info. Apenas os erros tornam valid falso.
code string Um código estável, por exemplo mjml.invalid-child, xml.unclosed-tag ou temple.unclosed-if. Consulte Códigos de diagnóstico.
message string Uma explicação legível.
line integer Linha na marcação, começando em 1. Apenas para código-fonte em marcação.
column integer Coluna na marcação, começando em 1. Apenas para código-fonte em marcação.
tag string O elemento a que o diagnóstico se refere.
attribute string O atributo a que o diagnóstico se refere.
path integer[] Caminho de índices de filhos a partir da raiz <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": []
    }
  ]
}

Renderizar MJML

Compila o MJML no HTML que o Emailit envia, com o MJML 5.4.1. Com variables, a resposta também inclui rendered_html: o HTML depois de o Temple ser aplicado, como um destinatário o receberia. Nada é salvo nem enviado. Requer uma chave de API com escopo full.

Este endpoint é limitado a 120 requisições por minuto.

POST/mjml/render

Parâmetros do corpo

sourcestring | objectObrigatório

O MJML a compilar: marcação MJML (<mjml>…</mjml>), MJML JSON ou um documento MJML do Emailit, como o source armazenado de um template. Consulte Formatos do código-fonte. Máximo de 2 MB.

variablesobject

Variáveis do Temple para rendered_html, como first_name, ou um objeto cf com os campos personalizados das campanhas. Nada é preenchido automaticamente: passe as variáveis que o canal de envio forneceria. Consulte Variáveis por canal. Precisa ser um objeto; qualquer outro valor retorna 400.

Retorno

Retorna 200 OK com o resultado, mesmo quando o MJML é inválido:

Campo Tipo Descrição
valid boolean true quando não há diagnósticos de erro.
mjml_version string A versão do MJML com que o Emailit compila.
html string ou null O HTML compilado, com as tags do Temple mantidas no lugar, como o Emailit o armazena para um template. null quando o MJML tem erros.
html_bytes integer Tamanho de html em UTF-8. O Gmail corta mensagens com mais de cerca de 102 KB. 0 quando html é null.
diagnostics array Todos os diagnósticos de erro, de aviso e de informação. Consulte Validar MJML.
rendered_html string ou null html com as variables aplicadas pelo Temple. Presente apenas quando você envia variables, e null quando o MJML tem erros.

Um MJML inválido retorna 200 com valid: false, html: null e os diagnósticos. rendered_html usa exatamente as variables que você envia: as variáveis ausentes são renderizadas como strings vazias ou como o valor padrão delas, então {{first_name|"there"}} renderiza there. O texto simples não é gerado a partir do MJML.

Retorna 422 com message: "Validation failed" quando source está ausente ou em branco, 400 quando variables não é um objeto e 403 com error: "mjml_alpha" sem acesso ao 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"
}

Obter a referência do MJML

Obtém todos os componentes e atributos da versão do MJML com que o Emailit compila, as versões atuais dos editores, o guia do Temple e as regras de escrita. Use-a para criar ferramentas de desenvolvimento ou para dar a um modelo de IA o que ele precisa para escrever templates MJML válidos. Requer uma chave de API com escopo full.

A mesma referência está disponível para agentes de IA como a ferramenta MCP get-mjml-reference. Consulte MJML para agentes de IA.

GET/mjml/reference

Retorno

Retorna 200 OK com a referência. O exemplo acima está resumido: components lista todos os 36 componentes com todos os atributos deles.

Campo Tipo Descrição
mjml_version string A versão do MJML com que o Emailit compila.
document_schema_version integer O schema_version atual do documento MJML armazenado.
editors object A versão e o estágio atuais (alpha, beta ou stable) de mjml-code e mjml-visual.
components array Todos os componentes do MJML. Veja abaixo.
temple_guide string Como o Temple funciona dentro do MJML: variáveis, valores padrão, condicionais e variáveis de campanhas.
rules string Regras de escrita de MJML: estrutura, atributos permitidos e acessibilidade.
reference_text string A referência completa dos componentes em texto simples compacto, para prompts.

Retorna 403 com error: "mjml_alpha" sem acesso ao MJML.

Objeto de componente

Campo Tipo Descrição
tag string Nome da tag, por exemplo mj-button.
label string Nome de exibição.
description string O que o componente faz.
category string root, head, layout, content, interactive, child ou advanced.
ending_tag boolean true quando o conteúdo é HTML bruto ou texto (mj-text, mj-button, mj-raw, …).
parents string[] Elementos dentro dos quais este componente pode ser colocado.
children string[] Elementos que este componente pode conter. ["*"] significa qualquer componente (mj-attributes).
attributes array Atributos, cada um com name, type (um tipo do MJML, como color, unit(px,%){1,4} ou enum(left,center,right)) e default (null quando não há valor padrão).
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]. …"
}

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.

Esc

Populares

↑↓para navegar↵para abrirEscpara fechar