---
title: "JSON to HTML"
method: POST
path: "/email/v1/json2html"
tags: ["Conversion API"]
---

# JSON to HTML

`POST /email/v1/json2html`

## Request

- Base URL: `https://api.topol.io`
- URL: `https://api.topol.io/email/v1/json2html`
- Auth: API key in header `X-Secret-Key`

Convert JSON template to HTML using MJML rendering engine. Authentication is done via the X-Secret-Key header.

If the template contains synced sections (any section node with a `syncedId` property), the matching content must be supplied through the optional `syncedSections` request field. Synced section references are resolved before merge tag evaluation and variant rendering: the endpoint looks up each `syncedId` in the supplied array, splices the section's full MJML into the template, regenerates child block UIDs to avoid collisions, and (for multilingual templates) merges per-locale translations into the template's `langs` array. Without this step, synced sections render as empty placeholders.

## Request body

- Json2HtmlRequest
  - `definition` string, required: JSON template definition
  - `options` object, required
    - `minify` boolean: Whether to minify the output HTML
    - `fonts` string: JSON string containing an array of font objects with label, style, and url properties
    - `emailServiceProvider` 'mailchimp' | 'sparkpost': Target email service provider
    - `mergeTags` unknown[]: Array of merge tags for template variable substitution
      - unknown
    - `evaluateMergeTags` boolean: Whether to evaluate merge tags in the template
    - `variants` object
      - `evaluate` boolean: Whether to evaluate variants
      - `enrichWithConditions` boolean: Whether to enrich with conditional logic
    - `desktopFirst` boolean: Whether to prioritize desktop layout
    - `language` string: Template language code
  - `syncedSections` object[]: Resolved content for every synced section referenced by the template. A section in the template JSON that carries a `syncedId` is stored as a lightweight reference only; the rendering pipeline must be supplied with the matching content here, otherwise the section renders empty. Fetch each referenced synced section from your saved-sections storage (see the Saved Blocks and Synced Sections guide) and pass it in this array before calling this endpoint.
    - `id` number, required: ID of the synced section. Must match the `syncedId` on a section node in the template JSON.
    - `definition` string, required: JSON-encoded MJML definition of the synced section (string, not a nested object).
    - `translation` string: Optional JSON-encoded locale-keyed translation map for multilingual templates. Required if the template has language mutations and the section contains translatable content.

## Response `200`

Template converted successfully

- Json2HtmlSuccess
  - `html` string, required: Rendered HTML output
  - `warnings` Warning[]: Optional warnings about the conversion
    - `type` 'missing_fonts', required: Type of warning
    - `message` string, required: Warning message
    - `missing_fonts` string[]: List of missing font names

## Other responses

- `400`: Bad request - missing or invalid request body
- `401`: Unauthorized - invalid or expired API key
- `422`: Validation error - invalid request format
- `500`: Internal server error

---

[API](https://skmtc.dev/topol/apis/topol-email-template-conversion-api.md) - [All operations](https://skmtc.dev/topol/apis/topol-email-template-conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/topol/apis/topol-email-template-conversion-api/revisions/cf1b58faada0?raw)