Email Templates

Create professional email templates with advanced personalization using merge variables.

Creating a Template

Template creation sends the actual reusable template content to the Communications API. HTML templates should include both an HTML body and a plain-text fallback.

curl -X POST https://motorical.com/comm-api/api/templates \
  -H "X-Tenant-Id: your-tenant-uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome {{name}}!",
    "type": "html",
    "body_html": "<!doctype html><html><body><h1>Hello {{name}}</h1><p>Welcome to {{identity_name}}.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p></body></html>",
    "body_text": "Hello {{name}},\n\nWelcome to {{identity_name}}.\n\nUnsubscribe: {{unsubscribe_url}}"
  }'

For text-only templates, set type to text and send body_text:

curl -X POST https://motorical.com/comm-api/api/templates \
  -H "X-Tenant-Id: your-tenant-uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plain Text Notice",
    "subject": "Update for {{name}}",
    "type": "text",
    "body_text": "Hello {{name}},\n\nHere is your update.\n\nUnsubscribe: {{unsubscribe_url}}"
  }'

Request Fields

Field	Required	Description
`name`	Yes	Internal template name shown in the dashboard.
`subject`	Yes	Email subject line. Merge variables are supported.
`type`	Yes	Template format. Use `html` for HTML templates or `text` for plain-text templates.
`body_html`	For `html` templates	Concrete HTML template body. Use email-safe HTML and inline styles for best client compatibility.
`body_text`	Recommended for `html`, required for `text`	Plain-text fallback or text-only body.

Validation

Use the validation endpoint to check concrete template HTML/text before saving it. Validation is non-destructive: it does not create a template, campaign, log, or queued email.

curl -X POST https://motorical.com/comm-api/api/templates/validate \
  -H "X-Tenant-Id: your-tenant-uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome {{name}}!",
    "type": "html",
    "body_html": "<!doctype html><html><body><h1>Hello {{name}}</h1><p>Welcome to {{identity_name}}.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p></body></html>",
    "body_text": "Hello {{name}},\n\nWelcome to {{identity_name}}.\n\nUnsubscribe: {{unsubscribe_url}}",
    "sampleData": {
      "name": "Ada Lovelace",
      "identity_name": "Example Co",
      "unsubscribe_url": "https://example.com/unsubscribe"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "warnings": [],
    "errors": [],
    "metrics": {
      "htmlSize": 168,
      "textLength": 75,
      "subjectLength": 17,
      "nodeCount": 8,
      "linkCount": 1,
      "imageCount": 0,
      "mergeVariables": ["identity_name", "name", "unsubscribe_url"]
    },
    "preview": {
      "subject": "Welcome Ada Lovelace!",
      "body_html": "<!doctype html><html><body><h1>Hello Ada Lovelace</h1><p>Welcome to Example Co.</p><p><a href=\"https://example.com/unsubscribe\">Unsubscribe</a></p></body></html>",
      "body_text": "Hello Ada Lovelace,\n\nWelcome to Example Co.\n\nUnsubscribe: https://example.com/unsubscribe"
    }
  }
}

The API validates the request shape before storing the template:

name, subject, and type are required.
type must match the body you provide: html templates need body_html; text templates need body_text.
Large HTML, high DOM node counts, too many links or images, script tags, javascript: URLs, event handlers, and missing unsubscribe placeholders are reported as warnings or errors.
HTML and text content are stored as reusable template bodies and later compiled for campaigns with merge variables and unsubscribe handling.
Use POST /comm-api/api/templates/validate before creation and GET /comm-api/api/templates/{id} after creation to inspect the stored content before using it in a campaign.

For production templates, use the same safety rules you use in the dashboard: email-safe HTML, inline CSS, a text fallback, and an unsubscribe placeholder.

Merge Variables

Dynamic content placeholders that are replaced per-recipient:

Variable	Description
`{{name}}`	Contact name
`{{identity_name}}`	Company/organization name
`{{unsubscribe_url}}`	Unsubscribe link (auto-generated)

Template Features

HTML & Text Templates — Rich HTML designs with automatic text fallbacks
Merge Variables — Dynamic content with {{name}}, {{identity_name}}, and custom fields
Automatic Unsubscribe — CAN-SPAM compliant unsubscribe links added automatically
Template Library — Reusable templates for consistent brand communication

Retrieving Templates

# Get all templates
GET /comm-api/api/templates
X-Tenant-Id: your-tenant-uuid

# Get template by ID
GET /comm-api/api/templates/{id}
X-Tenant-Id: your-tenant-uuid

Updating a Template

curl -X PATCH https://motorical.com/comm-api/api/templates/{id} \
  -H "X-Tenant-Id: your-tenant-uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Welcome Email",
    "subject": "Welcome {{name}} to our platform!",
    "type": "html",
    "body_html": "<p>Updated content</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
    "body_text": "Updated content\n\nUnsubscribe: {{unsubscribe_url}}"
  }'

Deleting Templates

# Delete a single template
DELETE /comm-api/api/templates/{id}
X-Tenant-Id: your-tenant-uuid

Best Practices

Always include a plain-text version alongside HTML
Test merge variables with sample data before sending
Use responsive HTML for mobile compatibility
Keep subject lines under 60 characters
Include a clear call-to-action

Creating a Template​

Request Fields​

Validation​

Merge Variables​

Template Features​

Retrieving Templates​

Updating a Template​

Deleting Templates​

Best Practices​