Templates API

The Templates API provides full CRUD (Create, Read, Update, Delete) operations for managing reusable email templates. You can create, list, view, update, and delete templates programmatically to use across broadcasts, sequences, and transactional emails.

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

• Read Permission: Required for GET endpoints (list, show)
• Write Permission: Required for POST, PATCH, DELETE endpoints

Template Object

The template object contains the following fields:

List Templates

GET /api/v1/templates

Retrieve a list of all templates for the authenticated broadcast channel, ordered alphabetically by label.

Query Parameters

• limit (optional): Maximum number of templates to return
• offset (optional): Number of templates to skip for pagination

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/templates

Response

{
  "data": [
    {
      "id": 1,
      "label": "Monthly Newsletter",
      "subject": "Your Monthly Update",
      "preheader": "See what's new this month",
      "body": "<p>Newsletter content here</p>",
      "html_body": true,
      "template_purpose": "general",
      "confirmation_text": null,
      "default_confirmation": false,
      "confirmation_page_settings": {},
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": 2,
      "label": "Subscription Confirmation",
      "subject": "Please confirm your subscription",
      "preheader": "One click to confirm",
      "body": "<p>Click <a href=\"{{ confirmation_url }}\">here</a> to confirm.</p>",
      "html_body": true,
      "template_purpose": "confirmation",
      "confirmation_text": "Thanks for confirming!",
      "default_confirmation": true,
      "confirmation_page_settings": {
        "confirmed": { "heading": "You're in!", "body": "Welcome to the list." }
      },
      "created_at": "2024-01-02T10:00:00Z",
      "updated_at": "2024-01-02T10:00:00Z"
    }
  ],
  "total": 2
}

Get Template

GET /api/v1/templates/:id

Retrieve details of a specific template.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/templates/123

Response

{
  "id": 123,
  "label": "Welcome Email",
  "subject": "Welcome to Our Community!",
  "preheader": "Thanks for joining us",
  "body": "<p>Welcome to the community! We're excited to have you.</p>",
  "html_body": true,
  "template_purpose": "general",
  "confirmation_text": null,
  "default_confirmation": false,
  "confirmation_page_settings": {},
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Create Template

POST /api/v1/templates

Create a new email template.

Parameters

• label (required): Internal name of the template (must be unique per channel)
• subject (required): Subject line of the email
• body (required): Content of the email
• preheader (optional): Preview text that appears in email clients
• html_body (optional): Whether the body contains HTML (default: false)
• template_purpose (optional): general (default) or confirmation. Set to confirmation to use this template for double opt-in confirmation emails.
• confirmation_text (optional): Legacy success-state body for the confirmation page. Only meaningful when template_purpose is confirmation.
• default_confirmation (optional): Boolean. When true, this template becomes the channel’s default confirmation template (any previous default is unset).
• confirmation_page_settings (optional): Per-state heading and body overrides for the confirmation page. See Confirmation Pages for the resolution chain. Shape: json { "confirmed": { "heading": "...", "body": "..." }, "expired": { "heading": "...", "body": "..." } } Allowed states: confirmed, already_confirmed, expired, not_found, confirmation_failed, fallback.

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "label": "Welcome Email",
      "subject": "Welcome to Our Community!",
      "preheader": "Thanks for joining us",
      "body": "<p>Welcome to the community! We are excited to have you.</p>",
      "html_body": true
    }
  }' \
  http://your-domain.com/api/v1/templates

Response

{
  "id": 123
}

Notes

• The label must be unique within your broadcast channel
• If html_body is set to true, the body should contain valid HTML
• Line breaks in HTML should use <br> tags, and paragraphs should be wrapped in <p> tags

Update Template

PATCH /api/v1/templates/:id

Update an existing template.

Parameters

All parameters are optional. Only include the fields you want to update:

• label: Internal name of the template
• subject: Subject line of the email
• body: Content of the email
• preheader: Preview text that appears in email clients
• html_body: Whether the body contains HTML
• template_purpose: general or confirmation
• confirmation_text: Legacy success-state body for the confirmation page
• default_confirmation: Boolean — set as channel default
• confirmation_page_settings: Per-state page copy overrides (see Create above for shape)

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "subject": "Updated Subject Line",
      "body": "<p>Updated content</p>"
    }
  }' \
  http://your-domain.com/api/v1/templates/123

Response

{
  "id": 123,
  "label": "Welcome Email",
  "subject": "Updated Subject Line",
  "preheader": "Thanks for joining us",
  "body": "<p>Updated content</p>",
  "html_body": true,
  "template_purpose": "general",
  "confirmation_text": null,
  "default_confirmation": false,
  "confirmation_page_settings": {},
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:30:00Z"
}

Delete Template

DELETE /api/v1/templates/:id

Delete a template.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/templates/123

Response

{
  "message": "Template deleted successfully"
}

Error Responses

If the request is invalid, the response will include an appropriate HTTP status code and error message:

401 Unauthorized

{
  "error": "Unauthorized"
}

This error occurs when: - No authorization header is provided - The token is invalid or expired - The token doesn’t have the required permissions

404 Not Found

{
  "error": "Template not found"
}

This error occurs when: - The template ID doesn’t exist - The template belongs to a different broadcast channel

422 Unprocessable Entity

{
  "error": "Label can't be blank, Subject can't be blank, Body can't be blank"
}

This error occurs when: - Required fields are missing - The label is already taken by another template in the same channel - Validation fails for any other reason

Usage Example: Syncing Templates from External System

Here’s an example of how you might sync templates from an external system:

# First, list existing templates
curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/templates

# Create a new template if it doesn't exist
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "label": "Product Update",
      "subject": "New Product Features",
      "preheader": "Check out what is new",
      "body": "<h1>New Features</h1><p>We have exciting updates to share!</p>",
      "html_body": true
    }
  }' \
  http://your-domain.com/api/v1/templates

# Update an existing template
curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "body": "<h1>New Features</h1><p>Updated content with more details!</p>"
    }
  }' \
  http://your-domain.com/api/v1/templates/123