Email Templates

Email templates allow you to create reusable email designs with dynamic content using Handlebars syntax. Templates are compiled at send-time with your custom parameters.

Templates work seamlessly with all email providers (Gmail, Microsoft, AWS SES) and support rich visual components.

Looking for component-based templates? Check out React Email for building emails with React components and TypeScript.

How Templates Work

graph LR
    A[Email Request] --> B[Template Compilation]
    B --> C[Handlebars Processing]
    C --> D[HTML Generation]
    D --> E[Email Sent]

Request: Send email with template_id and params
Compilation: Template Engine compiles template with parameters
Generation: Handlebars generates final HTML and subject
Delivery: Email sent via your configured provider

Quick Start

1. Create a Template

Use the visual editor or API to create a template:

curl -X POST https://api.keplars.com/api/v1/templates/save \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "description": "Welcome new users",
    "category": "onboarding",
    "blocks": [
      {
        "type": "header",
        "content": {
          "companyName": "{{companyName}}",
          "logo": "https://example.com/logo.png"
        },
        "styles": {
          "padding": "20px",
          "textAlign": "center"
        }
      },
      {
        "type": "text",
        "content": {
          "text": "Hello {{userName}}, welcome to {{companyName}}!"
        },
        "styles": {
          "padding": "20px",
          "fontSize": "16px"
        }
      }
    ],
    "workspace_id": "your-workspace-id"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "019a83de-2fc2-7b5f-bfbc-c951fe1200f7",
    "name": "Welcome Email",
    "created_at": "2026-01-18T10:00:00Z"
  }
}

2. Send Email with Template

curl -X POST https://api.keplars.com/api/v1/send-email/instant \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "template_id": "019a83de-2fc2-7b5f-bfbc-c951fe1200f7",
    "params": {
      "userName": "John Doe",
      "companyName": "Keplars"
    }
  }'

Important: When using templates, do NOT provide subject, body, or html fields. These come from the template itself.

Block Type	Description	Use Case
`header`	Company name/logo	Email branding
`hero`	Headline + CTA	Main message
`text`	Paragraph content	Body text
`image`	Images with captions	Visual content
`button`	Call-to-action buttons	Links
`columns2`	Two-column layout	Side-by-side content
`columns3`	Three-column layout	Product grids
`social`	Social media links	Footer
`footer`	Unsubscribe links	Compliance
`video`	Video thumbnails	Media content
`testimonial`	Customer quotes	Social proof
`event`	Event details	Invitations
`divider`	Horizontal line	Section separator
`spacer`	Vertical spacing	Layout

Block Example

{
  "type": "text",
  "content": {
    "text": "Dear {{userName}}, your order #{{orderNumber}} has been confirmed!"
  },
  "styles": {
    "padding": "20px",
    "fontSize": "16px",
    "color": "#333333"
  }
}

Handlebars Syntax

Variables

Use double curly braces for dynamic content:

Hello {{userName}}!
Your account expires on {{expiryDate}}.

Helpers

Built-in helpers for data formatting:

Comparison Helpers

{{#if (eq status "premium")}}
  Premium features unlocked!
{{/if}}

{{#if (gt credits 100)}}
  You have bonus credits!
{{/if}}

Text Formatting

{{uppercase companyName}}     → KEPLARS
{{lowercase email}}            → [email protected]
{{capitalize userName}}        → John Doe
{{truncate description 100}}  → First 100 chars...

Date Formatting

{{formatDate orderDate "short"}}    → 1/15/2026
{{formatDate orderDate "long"}}     → Wednesday, January 15, 2026
{{formatDate orderDate "time"}}     → 10:30:00 AM

Currency Formatting

{{currency amount "USD"}}  → $1,234.56
{{currency price "EUR"}}   → €999.00

Logic Helpers

{{#if (and isActive isPremium)}}
  Premium active user
{{/if}}

{{#if (or isAdmin isModerator)}}
  You have elevated permissions
{{/if}}

Complete Example

{
  "type": "text",
  "content": {
    "text": "{{#if isPremium}}Premium{{else}}Standard{{/if}} user {{capitalize userName}} - Account expires {{formatDate expiryDate 'long'}}"
  }
}

Template API Reference

Create Template

POST /api/v1/templates/save
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Template Name",
  "description": "Template description",
  "category": "marketing",
  "blocks": [...],
  "settings": {
    "backgroundColor": "#ffffff",
    "width": 600
  },
  "workspace_id": "workspace-uuid"
}

List Templates

GET /api/v1/templates/list?workspace_id=workspace-uuid
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "data": [
    {
      "id": "template-uuid",
      "name": "Welcome Email",
      "category": "onboarding",
      "is_ai_generated": false,
      "usage_count": 42,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Get Template Details

GET /api/v1/templates/details/{template_id}
Authorization: Bearer YOUR_API_KEY

Update Template

PUT /api/v1/templates/update/{template_id}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Updated Template Name",
  "blocks": [...]
}

Delete Template

DELETE /api/v1/templates/delete/{template_id}
Authorization: Bearer YOUR_API_KEY

Sending Emails with Templates

Basic Template Email

const response = await fetch('https://api.keplars.com/api/v1/send-email/instant', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: ['[email protected]'],
    template_id: '019a83de-2fc2-7b5f-bfbc-c951fe1200f7',
    params: {
      userName: 'John Doe',
      orderNumber: '12345',
      orderDate: '2026-01-18',
      amount: 99.99
    }
  })
});

Priority Levels with Templates

Templates work with all priority levels:

// Instant (0-5 seconds) - 2FA, OTP
POST /api/v1/send-email/instant

// High (0-30 seconds) - Alerts
POST /api/v1/send-email/high

// Normal (0-5 minutes) - Regular
POST /api/v1/send-email/async

// Low (when idle) - Marketing
POST /api/v1/send-email/bulk

Batch Emails with Templates

{
  "emails": [
    {
      "to": ["[email protected]"],
      "template_id": "welcome-template-id",
      "params": { "userName": "User 1" }
    },
    {
      "to": ["[email protected]"],
      "template_id": "welcome-template-id",
      "params": { "userName": "User 2" }
    }
  ],
  "priority": "normal"
}

Template Categories

Organize templates by category:

general - Miscellaneous emails
marketing - Promotional content
transactional - Orders, receipts
newsletter - Regular updates
onboarding - Welcome emails
support - Help emails
events - Invitations
ecommerce - Shopping

Best Practices

Design Guidelines

Mobile-First: Templates are responsive by default
Image Formats: Use JPG, PNG, GIF, WebP (NOT SVG)
Width: Recommended 600px for email clients
Colors: Use hex codes for consistency
Fonts: Stick to web-safe fonts (Arial, Helvetica, sans-serif)

Variable Naming

// ✅ Good - Clear and descriptive
{
  "userName": "John",
  "orderNumber": "12345",
  "expiryDate": "2026-12-31"
}

// ❌ Bad - Unclear abbreviations
{
  "un": "John",
  "on": "12345",
  "ed": "2026-12-31"
}

Testing Templates

Always test templates before sending to customers:

# Get template preview
curl -X POST https://api.keplars.com/api/v1/templates/compile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "your-template-id",
    "params": {
      "userName": "Test User",
      "orderNumber": "TEST-001"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "subject": "Order Confirmation for Test User",
    "compiled_html": "<html>...</html>",
    "plain_text": "Order Confirmation..."
  }
}

Validation Rules

Template Email Rules

Validation Errors:

❌ Cannot provide subject when using template_id
❌ Cannot provide body when using template_id
❌ Cannot provide html when using template_id
❌ Must provide params when using template_id

// ❌ INVALID - Subject with template
{
  "to": ["[email protected]"],
  "template_id": "abc123",
  "subject": "Hello",  // ❌ ERROR: Subject comes from template
  "params": {}
}

// ✅ VALID - Template only
{
  "to": ["[email protected]"],
  "template_id": "abc123",
  "params": { "userName": "John" }
}

Troubleshooting

Common Issues

Template Not Found

{
  "error": "Template not found"
}

Solution: Verify template_id exists and is active

Missing Parameters

{
  "error": "Template params are required when using template_id"
}

Solution: Provide params object with required variables

Compilation Failed

{
  "error": "Template compilation failed: Not Found"
}

Solution: Check template engine is running and template exists

Invalid Image Format

[WARNING] Image format not supported in email clients

Solution: Convert SVG images to PNG/JPG

Advanced Features

AI Template Generation

Generate templates using AI:

curl -X POST https://api.keplars.com/api/v1/templates/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a professional order confirmation email with order summary, shipping details, and support contact",
    "category": "transactional",
    "workspace_id": "your-workspace-id"
  }'

See AI Templates for more details.

Image Validation

The system validates image formats for email compatibility:

// Supported formats
✅ JPG, JPEG, PNG, GIF, WebP

// Unsupported formats (will show warnings)
❌ SVG, BMP, TIFF, ICO, HEIC, AVIF

Next Steps

React Email - Build emails with React components
Send Emails - Learn how to send emails
AI Templates - Generate templates with AI
Examples - See language-specific examples
Webhooks - Track email delivery

Start creating professional email templates today with Keplars Mail Service!

Email Templates

On this page