Features

Templates

Create and manage email templates

Overview

Templates are reusable email layouts that you can compose with the rich text editor or the visual block editor. Each template stores a name, subject line, HTML body, optional plain-text body, and a category for organization.

When composing an email, you can select a template to pre-fill the subject and body, then customize it before sending. The platform also ships with a library of built-in starter templates you can import into your account.

List Templates

Retrieve all templates, ordered by most recently updated.

GET/api/templates

List all templates sorted by last updated.

Response

json

{
  "templates": [
    {
      "id": 1,
      "name": "Welcome Email",
      "subject": "Welcome to our platform!",
      "html_body": "<h1>Welcome!</h1><p>Thanks for joining.</p>",
      "text_body": null,
      "category": "onboarding",
      "editor_type": "richtext",
      "blocks_json": null,
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-12T14:30:00Z"
    }
  ]
}

Get Template

Fetch a single template by ID. Returns 404 if the template does not exist.

GET/api/templates/[id]

Retrieve a single template by its ID.

Response

json

{
  "template": {
    "id": 1,
    "name": "Welcome Email",
    "subject": "Welcome to our platform!",
    "html_body": "<h1>Welcome!</h1><p>Thanks for joining.</p>",
    "text_body": null,
    "category": "onboarding",
    "editor_type": "richtext",
    "blocks_json": null,
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-12T14:30:00Z"
  }
}

Create Template

Create a new template. The name, subject, and HTML body are required. The category defaults to "general" if not specified.

POST/api/templates

Create a new email template. Returns the new template ID.

Parameters

Name	Type	Description
`name`*	string	Template display name
`subject`*	string	Email subject line
`htmlBody`*	string	HTML email body
`textBody`	string	Plain-text fallback body
`category`	string	Category for organization (default: "general")

Request

json

{
  "name": "Monthly Newsletter",
  "subject": "Your {{month}} Update",
  "htmlBody": "<h1>Monthly Update</h1><p>Here is what happened...</p>",
  "textBody": "Monthly Update\nHere is what happened...",
  "category": "newsletter"
}

Response

json

{
  "id": 5
}

Update Template

Update an existing template. All fields are sent in the request body. The updated_at timestamp is set automatically.

PUT/api/templates/[id]

Update a template by ID.

Parameters

Name	Type	Description
`name`*	string	Template name
`subject`*	string	Email subject line
`htmlBody`*	string	HTML email body
`textBody`	string	Plain-text fallback
`category`	string	Template category
`blocksJson`	string	JSON string of block editor data
`editorType`	string	"richtext" or "blocks" (default: "richtext")

Request

json

{
  "name": "Monthly Newsletter",
  "subject": "Your March Update",
  "htmlBody": "<h1>Updated Content</h1>",
  "category": "newsletter",
  "editorType": "richtext"
}

Response

json

{
  "success": true
}

Built-in Templates

The platform ships with a library of professionally designed starter templates. You can browse them by category and import any template into your account to use as a starting point.

GET/api/templates/builtin

List all built-in starter templates. Optionally filter by category.

Parameters

Name	Type	Description
`category`	string	Filter by category (e.g. "marketing", "transactional"). Use "all" or omit for all templates.

Response

json

{
  "templates": [
    {
      "id": "welcome-01",
      "name": "Welcome Email",
      "subject": "Welcome aboard!",
      "category": "onboarding",
      "description": "Clean welcome email for new signups"
    }
  ]
}

To import a built-in template into your account, send a POST to the same endpoint with the template ID:

Import Built-in Template

POST /api/templates/builtin
{
  "templateId": "welcome-01"
}

// Response:
{
  "success": true,
  "id": 12
}

Block Editor

In addition to the rich text editor, templates support a visual block editor. The block editor lets you compose emails from drag-and-drop content blocks such as headings, text paragraphs, images, buttons, dividers, and spacers.

Block-based templates store their structure in the blocks_json field as a JSON string. When saving, set editorType to "blocks" so the UI knows which editor to open.

blocks_json example

{
  "blocks": [
    { "type": "heading", "content": "Welcome!", "level": 1 },
    { "type": "text", "content": "Thanks for signing up." },
    { "type": "button", "text": "Get Started", "url": "https://example.com" },
    { "type": "divider" },
    { "type": "text", "content": "Questions? Reply to this email." }
  ]
}

The HTML body is generated automatically from the block data when composing or sending, so you always have both a structured representation and a rendered HTML version of the template.

Contacts Emails