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 name (unique)
slug string No URL-friendly identifier (auto-generated from name if omitted)
subject string Yes Email subject (supports {{variables}})
html_content string Yes HTML body
text_content string No Plain text body
description string No Human-readable description
type string No Type: transactional, marketing, system (default: transactional)
settings object No Template-specific settings

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_content": "<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>",
    "text_content": "Welcome, {{name}}!\n\nYour account is ready.",
    "description": "Sent to new users after signup",
    "type": "transactional"
  }'

Response

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Welcome to {{company_name}}, {{name}}!",
  "description": "Sent to new users after signup",
  "type": "transactional",
  "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 (default: 1)
per_page integer Items per page (default: 25, max: 100)
type string Filter by type: transactional, marketing, system
status string Filter: draft, active, archived
search string Search by name and description

Example request

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

Response

{
  "data": [
    {
      "id": "tmpl_abc123",
      "name": "welcome_email",
      "subject": "Welcome to {{company_name}}, {{name}}!",
      "type": "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",
  "type": "transactional",
  "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
name string New name
slug string New slug
subject string New subject line
html_content string New HTML body
text_content string New text body
description string New description
type string New type
settings object New settings

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
data object Yes Template 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 '{
    "data": {
      "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"
    }
  ]
}

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"
}

Publish template

Activate a template for use.

POST /v1/templates/{template_id}/publish

Example request

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

Response

Returns the updated template with "status": "active".

Archive template

Archive a template (soft disable).

POST /v1/templates/{template_id}/archive

Example request

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

Response

Returns the updated template with "status": "archived".

Template stats

Get template usage statistics.

GET /v1/templates/stats

Example request

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

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