Email Templates Guide

Email templates allow you to create reusable email designs that can be referenced when sending emails. This guide covers creating, managing, and using templates effectively.

Overview

Templates provide:

Consistency: Maintain brand standards across all emails
Efficiency: Avoid duplicating content in every send request
Maintainability: Update once, apply everywhere
Separation of Concerns: Designers create templates, developers trigger sends

Create a Template

Endpoint

POST /v1/email/template

Authentication

Requires Bearer token authentication.

Request Body

Field	Type	Required	Description
`name`	string	✅ Yes	A descriptive name for the template. Used for identification in lists and logs. Should be unique and meaningful (e.g., "Welcome Email", "Password Reset").
`subject`	string	✅ Yes	The default email subject line. Can include template variables using `{{variable}}` syntax.
`content`	array	✅ Yes	Array of content objects containing the email body in different formats.

Content Object

Field	Type	Required	Description
`type`	string	✅ Yes	MIME type of the content. Must be `"text/html"` or `"text/plain"`.
`value`	string	✅ Yes	The actual email content. HTML or plain text depending on type. Can include template variables.

Example Request

curl -X POST https://api.edith.example.com/v1/email/template \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome to {{company_name}}, {{first_name}}!",
    "content": [
      {
        "type": "text/html",
        "value": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><style>body{font-family:Arial,sans-serif;line-height:1.6;color:#333}.container{max-width:600px;margin:0 auto;padding:20px}.header{background:#007bff;color:white;padding:20px;text-align:center}.button{display:inline-block;background:#007bff;color:white;padding:12px 24px;text-decoration:none;border-radius:4px}</style></head><body><div class=\"container\"><div class=\"header\"><h1>Welcome to {{company_name}}!</h1></div><div class=\"content\"><p>Hi {{first_name}},</p><p>Thank you for joining us! We are excited to have you on board.</p><p>To get started, click the button below:</p><p><a href=\"{{getting_started_url}}\" class=\"button\">Get Started</a></p><p>If you have any questions, feel free to reply to this email.</p><p>Best regards,<br>The {{company_name}} Team</p></div></div></body></html>"
      },
      {
        "type": "text/plain",
        "value": "Welcome to {{company_name}}!\n\nHi {{first_name}},\n\nThank you for joining us! We are excited to have you on board.\n\nTo get started, visit: {{getting_started_url}}\n\nIf you have any questions, feel free to reply to this email.\n\nBest regards,\nThe {{company_name}} Team"
      }
    ]
  }'

Response

{
  "success": true,
  "template_id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA"
}

Field	Description
`success`	Boolean indicating the template was created
`template_id`	Unique identifier for the template. Use this ID when sending emails.

Get a Template

Endpoint

GET /v1/email/template/{id}

Purpose

Retrieve the full details of a specific template including its content.

Path Parameters

Parameter	Type	Required	Description
`id`	string	✅ Yes	The template ID returned when creating the template

Example Request

curl -X GET https://api.edith.example.com/v1/email/template/template_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "template": {
    "name": "Welcome Email",
    "subject": "Welcome to {{company_name}}, {{first_name}}!",
    "content": [
      {
        "type": "text/html",
        "value": "<!DOCTYPE html>..."
      },
      {
        "type": "text/plain",
        "value": "Welcome to {{company_name}}!..."
      }
    ]
  }
}

List All Templates

Endpoint

GET /v1/email/templates

Purpose

Retrieve a paginated list of all templates with their names and IDs. Useful for displaying templates in a UI or finding template IDs.

Query Parameters

Parameter	Type	Required	Description
`pageSize`	integer	No	Number of templates per page. Default: 20, Maximum: 50
`pageToken`	string	No	Pagination token from a previous response

Example Request

curl -X GET "https://api.edith.example.com/v1/email/templates?pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "templates": [
    {
      "id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA",
      "name": "Welcome Email"
    },
    {
      "id": "template_01JC3BCDEFGHIJK7890LMNO",
      "name": "Password Reset"
    },
    {
      "id": "template_01JC3BQRSTUVWXYZ123456",
      "name": "Order Confirmation"
    }
  ],
  "next_page_token": "eyJJZCI6InRlbXBsYXRlXzAxSjM..."
}

Field	Description
`templates`	Array of template summaries with ID and name
`next_page_token`	Token to fetch the next page. `null` if no more pages.

Pagination Example

# First page
curl -X GET "https://api.edith.example.com/v1/email/templates?pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Next page using the token from previous response
curl -X GET "https://api.edith.example.com/v1/email/templates?pageSize=10&pageToken=eyJJZCI6InRlbXBsYXRlXzAxSjM..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Update a Template

Endpoint

PUT /v1/email/template

Purpose

Modify an existing template. You can update the name, subject, content, or any combination.

Request Body

Field	Type	Required	Description
`template_id`	string	✅ Yes	The ID of the template to update
`name`	string	No	New name for the template. Only updated if provided.
`subject`	string	No	New subject line. Only updated if provided.
`content`	array	No	New content array. Only updated if provided.

Example Request - Update Subject Only

curl -X PUT https://api.edith.example.com/v1/email/template \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "subject": "Welcome aboard, {{first_name}}! 🎉"
  }'

Example Request - Full Update

curl -X PUT https://api.edith.example.com/v1/email/template \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "name": "Welcome Email v2",
    "subject": "Welcome aboard, {{first_name}}! 🎉",
    "content": [
      {
        "type": "text/html",
        "value": "<!DOCTYPE html><html>... updated content ...</html>"
      },
      {
        "type": "text/plain",
        "value": "Updated plain text version..."
      }
    ]
  }'

Response

{
  "success": true,
  "template_id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA"
}

Delete a Template

Endpoint

DELETE /v1/email/template/{id}

Purpose

Permanently delete a template.

⚠️ Warning: This action cannot be undone. Ensure no active email workflows depend on this template.

Path Parameters

Parameter	Type	Required	Description
`id`	string	✅ Yes	The template ID to delete

Example Request

curl -X DELETE https://api.edith.example.com/v1/email/template/template_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true
}

Using Templates When Sending Emails

Reference a template by its ID when calling the send endpoint:

Example: Send Using Template

curl -X POST https://api.edith.example.com/v1/email/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "hello@mail.yourcompany.com",
      "name": "YourCompany"
    },
    "to": [
      {
        "email": "newuser@example.com",
        "name": "New User"
      }
    ],
    "mailer_id": "domain_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "template_id": "template_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "substitutions": {
      "newuser@example.com": {
        "first_name": "Alex",
        "company_name": "YourCompany",
        "getting_started_url": "https://yourcompany.com/start"
      }
    },
    "settings": {
      "open_tracking": { "enable": true },
      "click_tracking": { "enable": true }
    }
  }'

Template Behavior

When using template_id:

Field	Behavior
`subject`	Uses template subject. Can be overridden by providing in request.
`content`	Uses template content. Can be overridden by providing in request.
`substitutions`	Variables in template are replaced with provided values

Template Variables

Templates support dynamic content using the {{variable}} syntax.

Syntax

<!-- Simple variable -->
<p>Hello {{first_name}},</p>

<!-- Multiple variables -->
<p>Your order #{{order_id}} for {{product_name}} has shipped.</p>

<!-- In URLs -->
<a href="{{tracking_url}}">Track your package</a>

<!-- In subject lines -->
Subject: "Your {{order_status}} update, {{first_name}}"

Passing Variables

Variables are passed through the substitutions field when sending:

{
  "substitutions": {
    "recipient@example.com": {
      "first_name": "Sarah",
      "order_id": "ORD-12345",
      "product_name": "Widget Pro",
      "tracking_url": "https://track.example.com/12345",
      "order_status": "shipping"
    }
  }
}

Variable Best Practices

Use Descriptive Names
- ✅ {{first_name}}, {{order_total}}, {{delivery_date}}
- ❌ {{fn}}, {{x1}}, {{d}}
Provide Fallback Content
- Design templates to gracefully handle missing variables
- Consider using default values in your sending logic
Document Required Variables
- Keep a list of variables each template expects
- Include in template naming: "Order Confirmation (order_id, items, total)"
Test Variable Substitution
- Send test emails to verify all variables render correctly
- Check both HTML and plain text versions

Template Design Best Practices

1. Mobile-First Design

<style>
  .container { max-width: 600px; margin: 0 auto; }
  @media (max-width: 600px) {
    .container { width: 100% !important; }
  }
</style>

2. Include Both HTML and Plain Text

Always provide both content types for maximum compatibility:

{
  "content": [
    { "type": "text/html", "value": "<html>...</html>" },
    { "type": "text/plain", "value": "Plain text version..." }
  ]
}

3. Use Web-Safe Fonts

font-family: Arial, Helvetica, sans-serif;

4. Inline Critical CSS

Email clients have limited CSS support. Inline important styles:

<p style="color: #333333; font-size: 16px;">Content here</p>

5. Optimize Images

Host images on a reliable CDN
Always include alt text
Use absolute URLs

<img src="https://cdn.yourcompany.com/logo.png" alt="Company Logo" width="200">

6. Test Across Clients

Test templates in:

Gmail (Web & Mobile)
Outlook (Desktop & Web)
Apple Mail
Yahoo Mail

Common Errors

Error	Cause	Solution
`name is required`	Missing template name	Provide a unique name
`subject is required`	Missing subject line	Add a subject
`content is required`	Missing content array	Provide at least one content object
`Template not found`	Invalid template_id	Verify the template exists
`Template ID is required`	Update without template_id	Include template_id for updates

Example Templates

Welcome Email

{
  "name": "Welcome Email",
  "subject": "Welcome to {{company_name}}!",
  "content": [
    {
      "type": "text/html",
      "value": "<div style=\"font-family:Arial,sans-serif;max-width:600px;margin:0 auto\"><h1 style=\"color:#007bff\">Welcome, {{first_name}}!</h1><p>We're thrilled to have you join {{company_name}}.</p><p><a href=\"{{dashboard_url}}\" style=\"background:#007bff;color:white;padding:12px 24px;text-decoration:none;border-radius:4px;display:inline-block\">Go to Dashboard</a></p></div>"
    }
  ]
}

Password Reset

{
  "name": "Password Reset",
  "subject": "Reset your password",
  "content": [
    {
      "type": "text/html",
      "value": "<div style=\"font-family:Arial,sans-serif;max-width:600px;margin:0 auto\"><h2>Password Reset Request</h2><p>Hi {{first_name}},</p><p>We received a request to reset your password. Click the button below to create a new password:</p><p><a href=\"{{reset_url}}\" style=\"background:#dc3545;color:white;padding:12px 24px;text-decoration:none;border-radius:4px;display:inline-block\">Reset Password</a></p><p>This link expires in {{expiry_hours}} hours.</p><p>If you didn't request this, please ignore this email.</p></div>"
    }
  ]
}

Order Confirmation

{
  "name": "Order Confirmation",
  "subject": "Order #{{order_id}} Confirmed",
  "content": [
    {
      "type": "text/html",
      "value": "<div style=\"font-family:Arial,sans-serif;max-width:600px;margin:0 auto\"><h1>Order Confirmed! ✅</h1><p>Thanks {{first_name}}, your order has been confirmed.</p><div style=\"background:#f8f9fa;padding:16px;border-radius:8px\"><p><strong>Order Number:</strong> {{order_id}}</p><p><strong>Total:</strong> {{order_total}}</p><p><strong>Estimated Delivery:</strong> {{delivery_date}}</p></div><p><a href=\"{{tracking_url}}\">Track your order</a></p></div>"
    }
  ]
}

Send an Email - Use templates when sending
Email Logs - Track template-based sends

Email Templates Guide

Overview​

Create a Template​

Endpoint​

Authentication​

Request Body​

Content Object​

Example Request​

Response​

Get a Template​

Endpoint​

Purpose​

Path Parameters​

Example Request​

Response​

List All Templates​

Endpoint​

Purpose​

Query Parameters​

Example Request​

Response​

Pagination Example​

Update a Template​

Endpoint​

Purpose​

Request Body​

Example Request - Update Subject Only​

Example Request - Full Update​

Response​

Delete a Template​

Endpoint​

Purpose​

Path Parameters​

Example Request​

Response​

Using Templates When Sending Emails​

Example: Send Using Template​

Template Behavior​

Template Variables​

Syntax​

Passing Variables​

Variable Best Practices​

Template Design Best Practices​

1. Mobile-First Design​

2. Include Both HTML and Plain Text​

3. Use Web-Safe Fonts​

4. Inline Critical CSS​

5. Optimize Images​

6. Test Across Clients​

Common Errors​

Example Templates​

Welcome Email​

Password Reset​

Order Confirmation​

Related Endpoints​

Overview

Create a Template

Endpoint

Authentication

Request Body

Content Object

Example Request

Response

Get a Template

Endpoint

Purpose

Path Parameters

Example Request

Response

List All Templates

Endpoint

Purpose

Query Parameters

Example Request

Response

Pagination Example

Update a Template

Endpoint

Purpose

Request Body

Example Request - Update Subject Only

Example Request - Full Update

Response

Delete a Template

Endpoint

Purpose

Path Parameters

Example Request

Response

Using Templates When Sending Emails

Example: Send Using Template

Template Behavior

Template Variables

Syntax

Passing Variables

Variable Best Practices

Template Design Best Practices

1. Mobile-First Design

2. Include Both HTML and Plain Text

3. Use Web-Safe Fonts

4. Inline Critical CSS

5. Optimize Images

6. Test Across Clients

Common Errors

Example Templates

Welcome Email

Password Reset

Order Confirmation

Related Endpoints