Documentation / API Reference

Templates API

3 min read

The Templates API lets you create, manage, and use reusable email templates.

Create template

Create a new email template.

POST /v1/templates

Request body

Field Type Required Description
name string Yes Template identifier (unique)
subject string Yes Email subject (supports variables)
html string Yes HTML body
text string No Plain text body (auto-generated if omitted)
description string No Human-readable description
category string No Category: transactional, marketing, notification
tags array No Tags for organization

Example request

curl -X POST https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_email",
    "subject": "Welcome to {{company_name}}, {{name}}!",
    "html": "<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>",
    "text": "Welcome, {{name}}!\n\nYour account is ready.",
    "description": "Sent to new users after signup",
    "category": "transactional",
    "tags": ["onboarding", "welcome"]
  }'

Response

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Welcome to {{company_name}}, {{name}}!",
  "description": "Sent to new users after signup",
  "category": "transactional",
  "tags": ["onboarding", "welcome"],
  "status": "active",
  "version": 1,
  "created_at": "2024-01-15T10:00:00Z"
}

List templates

Retrieve all templates.

GET /v1/templates

Query parameters

Parameter Type Description
page integer Page number
per_page integer Items per page
category string Filter by category
tag string Filter by tag
status string Filter: active, inactive

Example request

curl "https://api.mailingapi.com/v1/templates?category=transactional" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "tmpl_abc123",
      "name": "welcome_email",
      "subject": "Welcome to {{company_name}}, {{name}}!",
      "category": "transactional",
      "status": "active",
      "version": 1,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 25
  }
}

Get template

Retrieve a specific template.

GET /v1/templates/{template_id}

Example request

curl https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Welcome to {{company_name}}, {{name}}!",
  "html": "<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>",
  "text": "Welcome, {{name}}!\n\nYour account is ready.",
  "description": "Sent to new users after signup",
  "category": "transactional",
  "tags": ["onboarding", "welcome"],
  "status": "active",
  "version": 3,
  "variables": ["company_name", "name"],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-18T14:30:00Z"
}

Update template

Update a template. Creates a new version.

PATCH /v1/templates/{template_id}

Request body

Field Type Description
subject string New subject line
html string New HTML body
text string New text body
description string New description
category string New category
tags array New tags
status string active or inactive

Example request

curl -X PATCH https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome aboard, {{name}}!",
    "html": "<h1>Welcome aboard, {{name}}!</h1><p>Let'\''s get started.</p>"
  }'

Response

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Welcome aboard, {{name}}!",
  "status": "active",
  "version": 4,
  "updated_at": "2024-01-20T16:00:00Z"
}

Delete template

Remove a template.

DELETE /v1/templates/{template_id}

Example request

curl -X DELETE https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content

Render template

Render a template with sample data.

POST /v1/templates/{template_id}/render

Request body

Field Type Required Description
variables object Yes Sample variable values

Example request

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "name": "John",
      "company_name": "Acme Inc"
    }
  }'

Response

{
  "subject": "Welcome to Acme Inc, John!",
  "html": "<h1>Welcome, John!</h1><p>Your account is ready.</p>",
  "text": "Welcome, John!\n\nYour account is ready."
}

List versions

Get all versions of a template.

GET /v1/templates/{template_id}/versions

Example request

curl https://api.mailingapi.com/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "version": 4,
      "subject": "Welcome aboard, {{name}}!",
      "changelog": "Updated greeting",
      "created_at": "2024-01-20T16:00:00Z",
      "created_by": "user@example.com"
    },
    {
      "version": 3,
      "subject": "Welcome to {{company_name}}, {{name}}!",
      "changelog": "Added company name",
      "created_at": "2024-01-18T14:30:00Z"
    }
  ]
}

Get version

Get a specific version of a template.

GET /v1/templates/{template_id}/versions/{version}

Response

{
  "id": "tmpl_abc123",
  "version": 3,
  "subject": "Welcome to {{company_name}}, {{name}}!",
  "html": "...",
  "text": "...",
  "created_at": "2024-01-18T14:30:00Z"
}

Restore version

Restore a previous template version.

POST /v1/templates/{template_id}/versions/{version}/restore

Example request

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/versions/2/restore \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "id": "tmpl_abc123",
  "version": 5,
  "message": "Restored version 2",
  "updated_at": "2024-01-20T17:00:00Z"
}

Duplicate template

Create a copy of an existing template.

POST /v1/templates/{template_id}/duplicate

Request body

Field Type Required Description
name string Yes Name for the new template

Example request

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/duplicate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "welcome_email_v2"}'

Response

{
  "id": "tmpl_new456",
  "name": "welcome_email_v2",
  "status": "active",
  "version": 1,
  "created_at": "2024-01-20T17:30:00Z"
}

Error codes

Code Description
template_not_found Template ID not found
name_already_exists Template name must be unique
invalid_template Template syntax error
version_not_found Version number not found
missing_variables Required variables not provided