Skip to main content

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​

FieldTypeRequiredDescription
namestring✅ YesA descriptive name for the template. Used for identification in lists and logs. Should be unique and meaningful (e.g., "Welcome Email", "Password Reset").
subjectstring✅ YesThe default email subject line. Can include template variables using {{variable}} syntax.
contentarray✅ YesArray of content objects containing the email body in different formats.

Content Object​

FieldTypeRequiredDescription
typestring✅ YesMIME type of the content. Must be "text/html" or "text/plain".
valuestring✅ YesThe 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"
}
FieldDescription
successBoolean indicating the template was created
template_idUnique 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​

ParameterTypeRequiredDescription
idstring✅ YesThe 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​

ParameterTypeRequiredDescription
pageSizeintegerNoNumber of templates per page. Default: 20, Maximum: 50
pageTokenstringNoPagination 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..."
}
FieldDescription
templatesArray of template summaries with ID and name
next_page_tokenToken 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​

FieldTypeRequiredDescription
template_idstring✅ YesThe ID of the template to update
namestringNoNew name for the template. Only updated if provided.
subjectstringNoNew subject line. Only updated if provided.
contentarrayNoNew 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​

ParameterTypeRequiredDescription
idstring✅ YesThe 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:

FieldBehavior
subjectUses template subject. Can be overridden by providing in request.
contentUses template content. Can be overridden by providing in request.
substitutionsVariables 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​

  1. Use Descriptive Names

    • ✅ {{first_name}}, {{order_total}}, {{delivery_date}}
    • ❌ {{fn}}, {{x1}}, {{d}}

  2. Provide Fallback Content

    • Design templates to gracefully handle missing variables
    • Consider using default values in your sending logic

  3. Document Required Variables

    • Keep a list of variables each template expects
    • Include in template naming: "Order Confirmation (order_id, items, total)"

  4. 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​

ErrorCauseSolution
name is requiredMissing template nameProvide a unique name
subject is requiredMissing subject lineAdd a subject
content is requiredMissing content arrayProvide at least one content object
Template not foundInvalid template_idVerify the template exists
Template ID is requiredUpdate without template_idInclude 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>"
    }
  ]
}