Guide6 min read

Canonical JSON API: Create Emails Programmatically

MiN8T Team

Email Engineering

April 12, 2026

1 What is the Canonical JSON API?

The Canonical JSON API lets you generate personalized, ready-to-send emails programmatically. You design a template with Smart Elements in the editor, then call the API with data to produce final HTML — no visual editor needed at send time.

This is how you'd integrate MiN8T into your own application or CI/CD pipeline: design the template once, then generate thousands of personalized variants via API.

Key capabilities:

Smart Element population — pass items to fill Smart Element containers
Variable replacement — replace {{variable}} placeholders with actual values
Element duplication — Smart Element containers are cloned for each item in your data array
AMP generation — produces both HTML and AMP HTML if the template uses AMP blocks

2 The Generate Endpoint

POST /api/v1/templates/:id/generate
Content-Type: application/json
MiN8T-Api-Auth: your-api-key

{
  "items": [
    {
      "title": "Samsung Galaxy Note 10",
      "price": "$999.99",
      "imgUrl": "https://cdn.shop.com/samsung.jpg",
      "url": "https://shop.com/samsung"
    },
    {
      "title": "iPhone 15 Pro",
      "price": "$1,199.99",
      "imgUrl": "https://cdn.shop.com/iphone.jpg",
      "url": "https://shop.com/iphone"
    }
  ]
}

Authentication: MiN8T-Api-Auth header with your account API key.

Limits: Maximum 50 items per request. Items array is required and must contain at least one item.

3 How It Works

Finds Smart Elements — scans the template hierarchy for containers, structures, or stripes with smartElement.enabled = true (checks both top-level and metadata.smart_element paths)
Clones per item — for each item in the items array, the Smart Element container is deep-cloned
Replaces variables — within each clone, {{fieldName}} placeholders in text blocks, image URLs, and button links are replaced with actual values from the item
Generates HTML — the populated template is serialized to email-safe HTML
Generates AMP HTML (optional) — if the template contains AMP blocks, AMP output is also generated

The API works with any template that has Smart Elements. Design a product card template with {{title}}, {{price}}, {{imgUrl}} variables, then pass different products at send time to generate unique emails for each recipient or segment.

4 Response Format

{
  "success": true,
  "data": {
    "html": "<!DOCTYPE html><html>...</html>",
    "amp_html": "<!doctype html><html amp4email>...</html>",
    "smart_elements_found": 1,
    "items_processed": 2
  }
}

The response includes the fully generated HTML, optional AMP HTML, and metadata about the generation (how many Smart Elements were found and items processed).

If the template has no Smart Elements, the API returns the template HTML as-is without variable replacement. Ensure your template has at least one Smart Element with enabled configuration.

5 Next Steps

What are Smart Elements? — design templates with data connections
What are Data Sources? — alternative to API for dynamic AMP content

Last updated: April 2026. All details verified against MiN8T's actual codebase implementation.