# MJML (alfa) API > Valide e renderize MJML e consulte a referência do MJML. Em alfa, aberto apenas à equipe do Emailit. URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer `. ## Validar MJML — POST /mjml/validate > Verifique o MJML como acontece ao salvar um template, sem salvá-lo. Retorna todos os diagnósticos com a linha de cada um. Alfa: aberto apenas à equipe do Emailit. # 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](/pt/docs/templates/mjml/#validation) para ver o que cada verificação cobre. > **O MJML está em alfa:** O MJML está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "mjml_alpha"`. Consulte [Quem pode usar o MJML](/pt/docs/templates/mjml/#who-can-use-mjml). `POST /mjml/validate` ## Parâmetros do corpo - `source` (string | object, obrigatório): O MJML a verificar: marcação MJML (`…`), MJML JSON ou um documento MJML do Emailit, como o `source` armazenado de um template. Consulte [Formatos do código-fonte](/pt/docs/templates/mjml/#source-formats). Máximo de 2 MB. **Requisição** `POST /mjml/validate` **Node.js** ```javascript const source = ` Hi {{first_name}} `; const response = await fetch('https://api.emailit.com/v2/mjml/validate', { method: 'POST', headers: { 'Authorization': 'Bearer your_api_key', 'Content-Type': 'application/json' }, body: JSON.stringify({ source }) }); const { valid, diagnostics } = await response.json(); ``` **cURL** ```bash curl -X POST https://api.emailit.com/v2/mjml/validate \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "source": "\n \n \n Hi {{first_name}}\n \n \n" }' ``` **200 Inválido** ```json { "valid": false, "mjml_version": "5.4.1", "format": "markup", "diagnostics": [ { "severity": "error", "code": "mjml.invalid-child", "message": " cannot be placed inside . Allowed parents: , .", "line": 3, "column": 6, "tag": "mj-column", "path": [0, 0] }, { "severity": "error", "code": "mjml.unknown-attribute", "message": " 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 to ; clients and screen readers use it.", "line": 1, "column": 2, "tag": "mjml", "path": [] }, { "severity": "info", "code": "mjml.missing-preview", "message": "Add an to control the inbox preview text.", "line": 1, "column": 2, "tag": "mjml", "path": [] } ] } ``` **200 Válido** ```json { "valid": true, "mjml_version": "5.4.1", "format": "markup", "diagnostics": [] } ``` **200 Não reconhecido** ```json { "valid": false, "mjml_version": "5.4.1", "format": null, "diagnostics": [ { "severity": "error", "code": "document.unrecognized", "message": "Expected MJML markup (…), MJML JSON or an Emailit MJML document." } ] } ``` **422** ```json { "message": "Validation failed", "errors": { "source": ["The source field is required."] } } ``` **403** ```json { "error": "mjml_alpha", "message": "MJML is in alpha and available only to Emailit platform admins." } ``` ## 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 ``. Para obter o HTML, use [Renderizar MJML](/pt/docs/api-reference/mjml/render/). 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](/pt/docs/templates/mjml/#diagnostic-codes). | | `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 ``. | --- Fonte: https://emailit.com/pt/docs/api-reference/mjml/validate/ ## Renderizar MJML — POST /mjml/render > Compile o MJML no HTML que o Emailit envia e veja a prévia com variáveis do Temple. Alfa: aberto apenas à equipe do Emailit. # 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. > **O MJML está em alfa:** O MJML está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "mjml_alpha"`. Consulte [Quem pode usar o MJML](/pt/docs/templates/mjml/#who-can-use-mjml). `POST /mjml/render` ## Parâmetros do corpo - `source` (string | object, obrigatório): O MJML a compilar: marcação MJML (`…`), MJML JSON ou um documento MJML do Emailit, como o `source` armazenado de um template. Consulte [Formatos do código-fonte](/pt/docs/templates/mjml/#source-formats). Máximo de 2 MB. - `variables` (object): 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](/pt/docs/templates/mjml/#variables-by-channel). Precisa ser um objeto; qualquer outro valor retorna `400`. **Requisição** `POST /mjml/render` **Node.js** ```javascript const source = ` Welcome Your account is ready Hi {{first_name|"there"}}, welcome aboard. Activate account `; const response = await fetch('https://api.emailit.com/v2/mjml/render', { method: 'POST', headers: { 'Authorization': 'Bearer your_api_key', 'Content-Type': 'application/json' }, body: JSON.stringify({ source, variables: { first_name: 'Ada', activation_url: 'https://example.com/activate?token=abc123' } }) }); const { html, rendered_html } = await response.json(); ``` **cURL** ```bash curl -X POST https://api.emailit.com/v2/mjml/render \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "source": "WelcomeYour account is readyHi {{first_name|\"there\"}}, welcome aboard.Activate account", "variables": { "first_name": "Ada", "activation_url": "https://example.com/activate?token=abc123" } }' ``` **200** ```json { "valid": true, "mjml_version": "5.4.1", "html": "\n…Hi {{first_name|\"there\"}}, welcome aboard.……\n", "html_bytes": 5267, "diagnostics": [], "rendered_html": "\n…Hi Ada, welcome aboard.……\n" } ``` **200 Inválido** ```json { "valid": false, "mjml_version": "5.4.1", "html": null, "html_bytes": 0, "diagnostics": [ { "severity": "error", "code": "mjml.invalid-child", "message": " cannot be placed inside . Allowed parents: , .", "line": 3, "column": 6, "tag": "mj-column", "path": [0, 0] }, { "severity": "error", "code": "mjml.unknown-attribute", "message": " 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 to ; clients and screen readers use it.", "line": 1, "column": 2, "tag": "mjml", "path": [] }, { "severity": "info", "code": "mjml.missing-preview", "message": "Add an to control the inbox preview text.", "line": 1, "column": 2, "tag": "mjml", "path": [] } ], "rendered_html": null } ``` **422** ```json { "message": "Validation failed", "errors": { "source": ["The source field is required."] } } ``` **403** ```json { "error": "mjml_alpha", "message": "MJML is in alpha and available only to Emailit platform admins." } ``` ## 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](/pt/docs/api-reference/mjml/validate/). | | `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. --- Fonte: https://emailit.com/pt/docs/api-reference/mjml/render/ ## Obter a referência do MJML — GET /mjml/reference > Todos os componentes e atributos do MJML que o Emailit suporta, as versões dos editores, o guia do Temple e as regras de escrita. Alfa: aberto apenas à equipe do Emailit. # 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](/pt/docs/templates/mjml/#mjml-for-ai-agents). > **O MJML está em alfa:** O MJML está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "mjml_alpha"`. Consulte [Quem pode usar o MJML](/pt/docs/templates/mjml/#who-can-use-mjml). `GET /mjml/reference` **Requisição** `GET /mjml/reference` **Node.js** ```javascript const response = await fetch('https://api.emailit.com/v2/mjml/reference', { headers: { 'Authorization': 'Bearer your_api_key' } }); const reference = await response.json(); ``` **cURL** ```bash curl https://api.emailit.com/v2/mjml/reference \ -H "Authorization: Bearer your_api_key" ``` **200** ```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: > (optional) + . …", "reference_text": "MJML 5.4.1 component reference. Format: name=type[default]. …" } ``` **403** ```json { "error": "mjml_alpha", "message": "MJML is in alpha and available only to Emailit platform admins." } ``` ## 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). | --- Fonte: https://emailit.com/pt/docs/api-reference/mjml/reference/