Templates

Create, list, and retrieve email templates. Templates can be created via the API or the TopMail dashboard, and referenced when sending emails.

POST

/templates

Create a new email template.

Body Parameters

Name	Type	Required	Description
name	string	Required	Template name (max 255 characters).
html	string	Required	HTML content used when sending emails.
description	string	Optional	Optional description (max 500 characters).
json_structure	object	Optional	Block-based structure for the visual editor. Required for the template to be editable in the dashboard. Without this, the editor opens blank.
json_structure.blocks	array	Optional	Ordered array of content blocks. Each block needs id (string), type (string), and content (object).
json_structure.settings	object	Optional	Template-level styling: fontFamily, contentWidth, backgroundColor, contentBackgroundColor, defaultTextColor.

html vs json_structure

The html field is what gets sent in emails. The json_structure is what the visual editor reads. Keep them in sync — html should be the rendered output of the blocks in json_structure.

Block types

Supported block types: header, text, button, image, divider, spacer, columns, social, dynamic, conditional, hero, profile, html, dropshadow. Each type has specific content fields — the most commonly used are text (html, alignment, color) and header (text, level, alignment, color).

curl -X POST https://api.topmail.so/api/v1/templates \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "html": "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
    "json_structure": {
      "blocks": [
        {
          "id": "block-1",
          "type": "header",
          "content": { "text": "Welcome!", "level": 1, "alignment": "center", "color": "#333333" }
        },
        {
          "id": "block-2",
          "type": "text",
          "content": { "html": "<p>Thanks for joining us.</p>", "alignment": "left", "color": "#333333" }
        }
      ],
      "settings": {
        "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif",
        "contentWidth": 600,
        "backgroundColor": "#F5F5F5",
        "contentBackgroundColor": "#FFFFFF",
        "defaultTextColor": "#333333"
      }
    }
  }'

{
  "data": {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Welcome Email",
    "html": "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
    "json_structure": {
      "blocks": [
        {
          "id": "block-1",
          "type": "header",
          "content": {
            "text": "Welcome!",
            "level": 1,
            "alignment": "center",
            "color": "#333333"
          }
        },
        {
          "id": "block-2",
          "type": "text",
          "content": {
            "html": "<p>Thanks for joining us.</p>",
            "alignment": "left",
            "color": "#333333"
          }
        }
      ],
      "settings": {
        "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif",
        "contentWidth": 600,
        "backgroundColor": "#F5F5F5",
        "contentBackgroundColor": "#FFFFFF",
        "defaultTextColor": "#333333"
      }
    },
    "created_at": "2025-01-15T12:00:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
  }
}

If you only pass html without json_structure, the template will work for sending emails but will appear blank when opened in the visual editor.

GET

/templates

List all templates with optional search.

Query Parameters

Name	Type	Required	Description
search	string	Optional	Search templates by name.
limit	integer	Optional	Number of templates to return (default: 100, max: 1000).
offset	integer	Optional	Number of templates to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/templates?search=welcome&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

The list endpoint does not include HTML content to reduce payload size. Use the single template endpoint below to retrieve the full content.

GET

/templates/:id

Retrieve a single template with its HTML content.

curl https://api.topmail.so/api/v1/templates/TEMPLATE_ID \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Welcome Email",
    "html": "<html><body><h1>Welcome, {{first_name}}!</h1><p>Thanks for signing up.</p></body></html>",
    "json_structure": null,
    "created_at": "2025-01-05T12:00:00.000Z",
    "updated_at": "2025-01-12T09:30:00.000Z"
  }
}

Using templates when sending emails

You can reference a template by its ID when sending an email via the Email Send API. Use template_id instead of html, and optionally pass template_data to substitute variables.

curl -X POST https://api.topmail.so/api/v1/email/send \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "jane@example.com",
    "subject": "Welcome to Acme!",
    "template_id": "TEMPLATE_ID",
    "template_data": {
      "first_name": "Jane",
      "company": "Acme Inc"
    }
  }'

Template variables use double-brace syntax: {{variable_name}}. Contact attributes like {{first_name}} and {{email}} are automatically populated from the contact record when the recipient exists in your workspace.