# MJML (alfaverze) API

> Validujte a vykreslujte MJML a načtěte referenci MJML. V alfaverzi, otevřené jen týmu Emailitu.

Základní URL: `https://api.emailit.com/v2`. Autentizujte se hlavičkou `Authorization: Bearer <API key>`.

## Validace MJML — POST /mjml/validate

> Zkontrolujte MJML stejně jako při uložení šablony, ale bez uložení. Vrací všechna diagnostická hlášení s jejich řádkem. Alfaverze: otevřená jen týmu Emailitu.

# Validace MJML

Zkontroluje MJML stejně jako uložení šablony (syntaxi XML, strukturu MJML, typy atributů a syntaxi Temple) a zkompiluje ho pomocí MJML 5.4.1. Nic se neuloží. Neplatné MJML i tak vrací `200`, s `valid: false` a diagnostickými hlášeními. Vyžaduje oprávnění `full`.

Co jednotlivé kontroly pokrývají, najdete v části [Validace](/cs/docs/templates/mjml/#validation).

> **MJML je v alfaverzi:** Dokud MJML testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "mjml_alpha"`. Viz [Kdo může MJML používat](/cs/docs/templates/mjml/#who-can-use-mjml).

`POST /mjml/validate`

## Parametry v těle požadavku

- `source` (string | object, povinné): MJML ke kontrole: značkování MJML (`<mjml>…</mjml>`), MJML JSON nebo dokument MJML Emailitu, například uložený `source` šablony. Viz [Formáty zdroje](/cs/docs/templates/mjml/#source-formats). Nejvýše 2 MB.

**Požadavek** `POST /mjml/validate`

**Node.js**

```javascript
const source = `<mjml>
  <mj-body>
    <mj-column>
      <mj-text colour="#333333">Hi {{first_name}}</mj-text>
    </mj-column>
  </mj-body>
</mjml>`;

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

**200 Neplatné**

```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": []
    }
  ]
}
```

**200 Platné**

```json
{
  "valid": true,
  "mjml_version": "5.4.1",
  "format": "markup",
  "diagnostics": []
}
```

**200 Nerozpoznáno**

```json
{
  "valid": false,
  "mjml_version": "5.4.1",
  "format": null,
  "diagnostics": [
    {
      "severity": "error",
      "code": "document.unrecognized",
      "message": "Expected MJML markup (<mjml>…), 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."
}
```

## Odpověď

Vrací `200 OK` s výsledkem, i když je MJML neplatné:

| Pole | Typ | Popis |
| --- | --- | --- |
| `valid` | boolean | `true`, když nejsou žádná chybová hlášení, takže šablonu s tímto zdrojem lze uložit. |
| `mjml_version` | string | Verze MJML, se kterou Emailit kompiluje. |
| `format` | string nebo null | Jak se zdroj přečetl: `markup`, nebo `json`. `null`, když ho nešlo přečíst. |
| `diagnostics` | array | Všechna hlášení typu chyba, varování a informace. |

`valid: true` znamená, že šablona s tímto zdrojem by se přijala. Opravte i varování: obvykle upozorňují na skutečné problémy, například chybějící `<mj-title>`. HTML získáte endpointem [Vykreslení MJML](/cs/docs/api-reference/mjml/render/).

Pokud `source` chybí nebo je prázdný, vrací `422` s `message: "Validation failed"`, a bez přístupu k MJML vrací `403` s `error: "mjml_alpha"`.

### Objekt hlášení

Pole, která se hlášení netýkají, se vynechávají.

| Pole | Typ | Popis |
| --- | --- | --- |
| `severity` | string | `error`, `warning` nebo `info`. Hodnotu `valid` změní na false jen chyby. |
| `code` | string | Stálý kód, například `mjml.invalid-child`, `xml.unclosed-tag` nebo `temple.unclosed-if`. Viz [Kódy hlášení](/cs/docs/templates/mjml/#diagnostic-codes). |
| `message` | string | Čitelné vysvětlení. |
| `line` | integer | Řádek ve značkování, číslovaný od 1. Jen u zdrojů ve značkování. |
| `column` | integer | Sloupec ve značkování, číslovaný od 1. Jen u zdrojů ve značkování. |
| `tag` | string | Prvek, kterého se hlášení týká. |
| `attribute` | string | Atribut, kterého se hlášení týká. |
| `path` | integer[] | Cesta indexů potomků od kořene `<mjml>`. |

---
Zdroj: https://emailit.com/cs/docs/api-reference/mjml/validate/

## Vykreslení MJML — POST /mjml/render

> Zkompilujte MJML do HTML, které Emailit odesílá, a zobrazte si jeho náhled s proměnnými Temple. Alfaverze: otevřená jen týmu Emailitu.

# Vykreslení MJML

Zkompiluje MJML pomocí MJML 5.4.1 do HTML, které Emailit odesílá. S `variables` obsahuje odpověď také `rendered_html`: HTML po zpracování jazykem Temple, jak by ho dostal jeden příjemce. Nic se neuloží ani neodešle. Vyžaduje oprávnění `full`.

Tento endpoint je omezený na 120 požadavků za minutu.

> **MJML je v alfaverzi:** Dokud MJML testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "mjml_alpha"`. Viz [Kdo může MJML používat](/cs/docs/templates/mjml/#who-can-use-mjml).

`POST /mjml/render`

## Parametry v těle požadavku

- `source` (string | object, povinné): MJML ke kompilaci: značkování MJML (`<mjml>…</mjml>`), MJML JSON nebo dokument MJML Emailitu, například uložený `source` šablony. Viz [Formáty zdroje](/cs/docs/templates/mjml/#source-formats). Nejvýše 2 MB.

- `variables` (object): Proměnné Temple pro `rendered_html`, například `first_name`, nebo objekt `cf` s vlastními poli, jaké používají kampaně. Nic se nevyplní automaticky: předejte proměnné, které by poskytl kanál, přes který se odesílá. Viz [Proměnné podle kanálu](/cs/docs/templates/mjml/#variables-by-channel). Musí to být objekt; cokoli jiného vrací `400`.

**Požadavek** `POST /mjml/render`

**Node.js**

```javascript
const 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>`;

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

**200**

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

**200 Neplatné**

```json
{
  "valid": false,
  "mjml_version": "5.4.1",
  "html": null,
  "html_bytes": 0,
  "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": []
    }
  ],
  "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."
}
```

## Odpověď

Vrací `200 OK` s výsledkem, i když je MJML neplatné:

| Pole | Typ | Popis |
| --- | --- | --- |
| `valid` | boolean | `true`, když nejsou žádná chybová hlášení. |
| `mjml_version` | string | Verze MJML, se kterou Emailit kompiluje. |
| `html` | string nebo null | Zkompilované HTML, ve kterém zůstávají značky Temple, tak jak ho Emailit ukládá u šablony. `null`, když MJML obsahuje chyby. |
| `html_bytes` | integer | Velikost `html` v UTF-8. Gmail ořezává zprávy větší než zhruba 102 KB. `0`, když je `html` `null`. |
| `diagnostics` | array | Všechna hlášení typu chyba, varování a informace. Viz [Validace MJML](/cs/docs/api-reference/mjml/validate/). |
| `rendered_html` | string nebo null | `html` s `variables` dosazenými jazykem Temple. Uvádí se, jen pokud pošlete `variables`, a když MJML obsahuje chyby, je `null`. |

Neplatné MJML vrací `200` s `valid: false`, `html: null` a diagnostickými hlášeními. `rendered_html` používá přesně ty `variables`, které pošlete: chybějící proměnné se vykreslí jako prázdné řetězce nebo jako svá výchozí hodnota, takže `{{first_name|"there"}}` vykreslí `there`. Prostý text se z MJML negeneruje.

Pokud `source` chybí nebo je prázdný, vrací `422` s `message: "Validation failed"`, pokud `variables` není objekt, vrací `400`, a bez přístupu k MJML vrací `403` s `error: "mjml_alpha"`.

---
Zdroj: https://emailit.com/cs/docs/api-reference/mjml/render/

## Načtení reference MJML — GET /mjml/reference

> Všechny komponenty a atributy MJML, které Emailit podporuje, verze editorů, průvodce jazykem Temple a pravidla pro psaní MJML. Alfaverze: otevřená jen týmu Emailitu.

# Načtení reference MJML

Načte všechny komponenty a atributy MJML ve verzi, se kterou Emailit kompiluje, aktuální verze editorů, průvodce jazykem Temple a pravidla pro psaní MJML. Použijte ji při tvorbě nástrojů, nebo když chcete AI modelu dát vše, co potřebuje k psaní platných šablon MJML. Vyžaduje oprávnění `full`.

Stejná reference je AI agentům dostupná jako nástroj MCP `get-mjml-reference`. Viz [MJML pro AI agenty](/cs/docs/templates/mjml/#mjml-for-ai-agents).

> **MJML je v alfaverzi:** Dokud MJML testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky, včetně všech požadavků s API klíčem, vracejí `403` s `error: "mjml_alpha"`. Viz [Kdo může MJML používat](/cs/docs/templates/mjml/#who-can-use-mjml).

`GET /mjml/reference`

**Požadavek** `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: <mjml> > <mj-head> (optional) + <mj-body>. …",
  "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."
}
```

## Odpověď

Vrací `200 OK` s referencí. Příklad výše je zkrácený: `components` obsahuje všech 36 komponent se všemi jejich atributy.

| Pole | Typ | Popis |
| --- | --- | --- |
| `mjml_version` | string | Verze MJML, se kterou Emailit kompiluje. |
| `document_schema_version` | integer | Aktuální `schema_version` uloženého dokumentu MJML. |
| `editors` | object | Aktuální verze a fáze vývoje (`alpha`, `beta` nebo `stable`) editorů `mjml-code` a `mjml-visual`. |
| `components` | array | Všechny komponenty MJML. Viz níže. |
| `temple_guide` | string | Jak Temple funguje uvnitř MJML: proměnné, výchozí hodnoty, podmínky a proměnné kampaní. |
| `rules` | string | Pravidla pro psaní MJML: struktura, povolené atributy a přístupnost. |
| `reference_text` | string | Celá reference komponent jako kompaktní prostý text pro prompty. |

Bez přístupu k MJML vrací `403` s `error: "mjml_alpha"`.

### Objekt komponenty

| Pole | Typ | Popis |
| --- | --- | --- |
| `tag` | string | Název tagu, například `mj-button`. |
| `label` | string | Zobrazovaný název. |
| `description` | string | Co komponenta dělá. |
| `category` | string | `root`, `head`, `layout`, `content`, `interactive`, `child` nebo `advanced`. |
| `ending_tag` | boolean | `true`, když je obsahem surové HTML nebo text (`mj-text`, `mj-button`, `mj-raw`, …). |
| `parents` | string[] | Prvky, do kterých lze tuto komponentu umístit. |
| `children` | string[] | Prvky, které tato komponenta může obsahovat. `["*"]` znamená jakoukoli komponentu (`mj-attributes`). |
| `attributes` | array | Atributy, každý s `name`, `type` (typ MJML, například `color`, `unit(px,%){1,4}` nebo `enum(left,center,right)`) a `default` (`null`, pokud výchozí hodnota není). |

---
Zdroj: https://emailit.com/cs/docs/api-reference/mjml/reference/