Email Templates API

Upload and manage Word document templates specifically formatted for email generation, including HTML conversion and variable replacement.

---

Base URL

https://app.datapublisher.io/api/email-templates

---

Authentication

All endpoints require JWT authentication via Authorization: Bearer header.

---

Overview

The Email Templates API allows you to:

Upload Word documents (.docx, .doc) as email templates

Convert Word documents to HTML for email rendering

Extract variables from templates for personalization

Manage template metadata (name, description)

Download template files

Delete unused templates

Supported File Types:

Word documents (.docx, .doc)

File Size Limit: 25 MB

Key Features:

Automatic HTML conversion from Word documents

Variable extraction ({{FieldName}} format)

Image embedding and optimization

Template versioning

Usage tracking

---

Endpoints

List Email Templates

Get all email templates for the authenticated user.

Endpoint: GET /list

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "templates": [ { "id": "uuid", "templateName": "Welcome Email", "description": "Welcome email for new customers", "originalFilename": "welcome-template.docx", "fileSize": 35000, "status": "active", "variables": ["FirstName", "CompanyName", "SignupDate"], "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-02-01T14:30:00Z" }, { "id": "uuid-2", "templateName": "Monthly Newsletter", "description": "Monthly company newsletter template", "originalFilename": "newsletter.docx", "fileSize": 125000, "status": "active", "variables": ["RecipientName", "Month", "Year", "TopStory"], "createdAt": "2026-01-20T09:00:00Z", "updatedAt": "2026-02-10T11:00:00Z" } ], "count": 2

}

---

Upload Email Template

Upload a new Word document as an email template.

Endpoint: POST /upload

Headers:

Authorization: Bearer

Content-Type: multipart/form-data

Form Data:

template (file, required): Word document (.docx or .doc)

templateName (string, required): Display name for template

description (string, optional): Template description

Response (200 OK):

{ "success": true, "template": { "id": "uuid", "templateName": "Welcome Email", "description": "Welcome email for new customers", "originalFilename": "welcome-template.docx", "fileName": "abc123-def456.docx", "fileSize": 35000, "status": "active", "variables": ["FirstName", "CompanyName", "SignupDate"], "createdAt": "2026-02-12T10:00:00Z" }, "message": "Email template uploaded successfully"

}

Error Responses:

400 Bad Request - Missing template name:

{
  "success": false,

  "message": "Template name is required"

}

400 Bad Request - No file provided:

{
  "success": false,

  "message": "No template file provided"

}

400 Bad Request - Invalid file type:

{
  "success": false,

  "message": "File type not supported. Only Word documents (.docx, .doc) are allowed."

}

---

Get Email Template

Retrieve metadata for a specific email template.

Endpoint: GET /:templateId

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "template": { "id": "uuid", "userId": "user-uuid", "templateName": "Welcome Email", "description": "Welcome email for new customers", "originalFilename": "welcome-template.docx", "fileName": "abc123.docx", "fileSize": 35000, "filePath": "/uploads/email-templates/user-uuid/abc123.docx", "status": "active", "variables": ["FirstName", "CompanyName", "SignupDate"], "htmlContent": "...", "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-02-01T14:30:00Z" }

}

Error Responses:

404 Not Found:

{
  "success": false,

  "message": "Email template not found"

}

---

Download Email Template

Download the original Word document file.

Endpoint: GET /:templateId/download

Headers:

Authorization: Bearer

Response (200 OK):

Binary file stream

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

Content-Disposition: attachment; filename="TemplateName.docx"

Content-Length: File size in bytes

Error Responses:

404 Not Found - Template not found:

{
  "success": false,

  "message": "Email template not found"

}

404 Not Found - File missing:

{
  "success": false,

  "message": "Template file not found"

}

---

Update Email Template

Update template metadata (name and description).

Endpoint: PUT /:templateId

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "templateName": "Welcome Email v2", "description": "Updated welcome email for new customers"

}

Response (200 OK):

{ "success": true, "template": { "id": "uuid", "templateName": "Welcome Email v2", "description": "Updated welcome email for new customers", "updatedAt": "2026-02-12T11:00:00Z" }, "message": "Email template updated successfully"

}

Error Responses:

404 Not Found:

{
  "success": false,

  "message": "Email template not found"

}

---

Delete Email Template

Permanently delete an email template and its file.

Endpoint: DELETE /:templateId

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "message": "Email template deleted successfully"

}

Error Responses:

404 Not Found:

{
  "success": false,

  "message": "Email template not found"

}

---

Template Variables

Supported Variable Format

Email templates support field placeholders in the format:

{{FieldName}}

Examples:

Dear {{FirstName}} {{LastName}},

Thank you for joining {{CompanyName}}!


Your account was created on {{SignupDate}}.

Variable Naming Rules

Must start with a letter

Can contain letters, numbers, underscores

Case-sensitive

No spaces or special characters

Examples: {{First_Name}}, {{Email2024}}, {{ContactEmail}}

Automatic Variable Extraction

When you upload a template:

The document is scanned for {{...}} patterns

All unique variables are extracted

Variables are available in the template metadata

Use the variables list to map data when sending emails

---

HTML Conversion

Automatic Conversion

Word documents are automatically converted to HTML for email rendering:

Supported Features:

Text formatting (bold, italic, underline)

Headings and paragraphs

Lists (bulleted and numbered)

Tables

Images (embedded and linked)

Text colors and highlighting

Font families and sizes

Alignment (left, center, right, justify)

Limitations:

Complex layouts may not render perfectly in all email clients

Some Word-specific features are simplified for email compatibility

Embedded fonts may fall back to web-safe fonts

Email Client Compatibility

HTML output is optimized for:

Outlook (desktop and web)

Gmail

Apple Mail

Thunderbird

Mobile email clients

---

Rate Limiting

Upload: 20 uploads per 15 minutes

General requests: 1000 per 15 minutes

---

Common Error Codes

| Status Code | Description |

|-------------|-------------|

| 400 | Invalid file type, missing required fields |

| 401 | Unauthorized - missing or invalid JWT token |

| 404 | Template not found or access denied |

| 413 | File too large (>25 MB) |

| 429 | Too many upload requests |

| 500 | Internal server error |

---

Usage Examples

JavaScript (Fetch API)

// Upload email template
const formData = new FormData();

formData.append('template', fileInput.files[0]);

formData.append('templateName', 'Welcome Email');

formData.append('description', 'Welcome email for new customers');


const uploadResponse = await fetch('https://app.datapublisher.io/api/email-templates/upload', {

  method: 'POST',

  headers: {

    'Authorization': Bearer ${jwtToken}

  },

  body: formData

});

const uploaded = await uploadResponse.json();

console.log('Template uploaded:', uploaded.template.id);

console.log('Variables found:', uploaded.template.variables);


// List templates

const listResponse = await fetch('https://app.datapublisher.io/api/email-templates/list', {

  headers: {

    'Authorization': Bearer ${jwtToken}

  }

});

const templates = await listResponse.json();

console.log(Found ${templates.count} templates);


// Get template details

const templateResponse = await fetch(

  https://app.datapublisher.io/api/email-templates/${templateId},
  {

    headers: {

      'Authorization': Bearer ${jwtToken}

    }

  }

);

const template = await templateResponse.json();

console.log('Variables:', template.template.variables);

Python (requests)

import requests

API_URL = 'https://app.datapublisher.io/api/email-templates'

headers = {'Authorization': f'Bearer {jwt_token}'}


Upload template

with open('welcome-email.docx', 'rb') as f:

    files = {'template': f}

    data = {

        'templateName': 'Welcome Email',

        'description': 'Welcome email for new customers'

    }

    response = requests.post(f'{API_URL}/upload', files=files, data=data, headers=headers)

    uploaded = response.json()

    template_id = uploaded['template']['id']

    print(f"Template uploaded: {template_id}")

    print(f"Variables: {uploaded['template']['variables']}")


List templates

response = requests.get(f'{API_URL}/list', headers=headers)

templates = response.json()

print(f"Found {templates['count']} templates")


Get template

response = requests.get(f'{API_URL}/{template_id}', headers=headers)

template = response.json()

print(f"Variables: {template['template']['variables']}")


Download template

response = requests.get(f'{API_URL}/{template_id}/download', headers=headers)

with open('downloaded-template.docx', 'wb') as f:

    f.write(response.content)

print("Template downloaded")

cURL

Upload template curl -X POST https://app.datapublisher.io/api/email-templates/upload \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -F "template=@welcome-email.docx" \ -F "templateName=Welcome Email" \ -F "description=Welcome email for new customers" List templates curl -X GET https://app.datapublisher.io/api/email-templates/list \ -H "Authorization: Bearer YOUR_JWT_TOKEN" Get template curl -X GET "https://app.datapublisher.io/api/email-templates/TEMPLATE_ID" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" Download template curl -X GET "https://app.datapublisher.io/api/email-templates/TEMPLATE_ID/download" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -o template.docx Delete template curl -X DELETE "https://app.datapublisher.io/api/email-templates/TEMPLATE_ID" \

-H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Best Practices

Template Design: Use simple, email-friendly layouts (avoid complex tables)

Variable Naming: Use consistent, descriptive variable names

Testing: Test templates with sample data before using in campaigns

Images: Keep images small (<100 KB each) for faster email loading

Mobile-Friendly: Design templates that work on mobile devices

Plain Text: Consider providing plain text fallback for variables

Version Control: Use descriptive template names with version numbers

Documentation: Document required variables in template description

File Size: Keep templates under 5 MB for faster processing

---

Template Design Tips

Good Template Structure

Subject: Welcome to {{CompanyName}}, {{FirstName}}!

Dear {{FirstName}},


Thank you for signing up on {{SignupDate}}.


We're excited to have you as part of {{CompanyName}}.


Best regards,

The {{CompanyName}} Team

Variables to Include

Personal:

FirstName, LastName

Email, Phone

CompanyName, Title

Dates:

SignupDate, CurrentDate

ExpirationDate, RenewalDate

Custom:

AccountNumber, OrderID

TotalAmount, ProductName

Any data from your CSV files

---

Email Templates API

Base URL

Authentication

Overview

Endpoints

List Email Templates

Upload Email Template

Get Email Template

Download Email Template

Update Email Template

Delete Email Template

Template Variables

Supported Variable Format

Variable Naming Rules

Automatic Variable Extraction

HTML Conversion

Automatic Conversion

Email Client Compatibility

Rate Limiting

Common Error Codes

Usage Examples

JavaScript (Fetch API)

Python (requests)

Upload template

List templates

Get template

Download template

cURL

Upload template

List templates

Get template

Download template

Delete template

Best Practices

Template Design Tips

Good Template Structure

Variables to Include

Related Documentation