Template API - Fields Reference

This article describes all fields available through the Template API. Use this as a reference when reading, creating, or updating templates.

---

Overview

The Template API lets you manage your Envoke email templates programmatically — create new templates, update existing ones, and retrieve template details including HTML content. Templates can be assigned to groups, tagged with a language, and toggled between published and unpublished states.

All endpoints require HTTP Basic Auth using your API ID and API Key.

---

Fields

Field	Type	Read-only	Required on Create	Description
id	string	Yes	—	Unique identifier assigned on creation. Returned as a string.
external_id	string	Yes	—	Randomly assigned identifier used to build the preview URL.
preview_url	string	Yes	—	Public URL to preview the template in a browser.
name	string	No	No	Template name. Minimum 3 characters. Auto-generated if omitted.
status	string (enum)	No	No	published or unpublished. Defaults to published on create if not specified.
language	string	No	No	IETF language code (e.g. en, fr). Defaults to en.
group	string	No	No	Name of the group the template belongs to. Empty string ("") when unset.
create_time	string	Yes	—	Timestamp when the template was created.
modified_time	string	Yes	—	Timestamp when the template was last modified.
html	string	—	See below	Full HTML content. Write on create/update; read only via ?include_html=1.

---

Field Details

id

• Type: String
• Read-only: Yes — assigned automatically on creation.
• Example: "42"

Used to identify the template in update, delete, and single-record GET requests.

---

external_id

• Type: String
• Read-only: Yes — assigned automatically on creation.
• Example: "a1b2c3d4e5f6g7h8"

A randomly assigned identifier. Not the same as id. Used to construct the preview_url.

---

preview_url

• Type: String
• Read-only: Yes — computed from the account’s external ID and the template’s external_id.
• Format: https://{domain}/m/{account_external_id}/m/{external_id}
• Example: "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6g7h8"

A public URL that shows the template in a browser without logging in. {domain} is your account’s custom domain if it has one, and otherwise Envoke’s message domain; it is not the API host. Use the URL as returned rather than building it yourself.

---

name

• Type: String
• Read-only: No — updatable via PATCH.
• Required on create: No — if omitted, auto-generated as API Template {timestamp}.
• Validation: Minimum 3 characters (applies when provided).
• Example: "Welcome Email"

---

status

• Type: String (enum)
• Read-only: No — updatable via PATCH.
• Required on create: No
• Allowed values: published, unpublished

Controls whether the template is available for use in campaigns.

On create, status defaults to published if not specified. Pass "unpublished" to create the template in a draft state. On PATCH, accepted values are "published" and "unpublished".

---

language

• Type: String
• Read-only: No — updatable via PATCH.
• Required on create: No — defaults to en.
• Accepted values (write): IETF language code (e.g. en) or numeric language ID.
• Returned value (read): Always the IETF language code.
• Example: "en", "fr"

Common supported codes: en, fr, ar, zh, de, it, ja, ko, pt, ru, es.

---

group

• Type: String
• Read-only: No — updatable via PATCH.
• Required on create: No
• Accepted values (write): Group name (string) or group ID (integer). The group must be of type message_template. Pass an empty string ("") to remove the group assignment.
• Returned value (read): The group name as a string. Returns "" (empty string) when no group is assigned.
• Example: "Marketing Templates", ""

---

create_time

• Type: String
• Read-only: Yes
• Format: Y-m-d H:i:s in the account’s configured timezone.
• Example: "2026-04-11 09:00:00"

---

modified_time

• Type: String
• Read-only: Yes
• Format: Y-m-d H:i:s in the account’s configured timezone.
• Example: "2026-04-11 14:22:10"

Updated automatically whenever the template is saved.

---

html

• Type: String
• Maximum size: 200 KB
• Write: Accepted in POST (create) and PATCH (update) request bodies.
• Read: Only returned on GET /v2/templates/{id}?include_html=1. Never included in list responses or in create/update response bodies.

The full HTML source of the template. On create, either html or template_id must be provided (see below).

---

Write-Only Field: template_id

Field	Type	Operations	Description
template_id	integer	POST only	ID of an existing template or message to copy HTML from.

template_id is a write-only convenience field for creating a new template by copying the HTML from an existing one. It is never returned in any GET response. The source must be owned by your account or accessible as a shared template.

Either html or template_id must be provided when creating a template. name is optional — if omitted, the template is named API Template {timestamp}. If neither html nor template_id is included, the request will fail with a validation error.

---

Error Responses

Validation errors (missing fields, invalid values, name too short, etc.):

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'name' must be at least 3 characters long"
    ]
  }
}

Some errors also include an allowed_values object listing the valid options for the offending field:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Invalid 'status'"],
    "allowed_values": {
      "status": ["published", "unpublished"]
    }
  }
}

Not-found behaviour varies by method:

• GET /templates/{id} — when the ID is not found, returns an empty array ([]).
• PATCH /templates/{id} — when the ID is not found, returns a validation error:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Item with id '999999' not found"]
  }
}

• DELETE /templates/{id} — when the ID is not found, returns a validation error:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Item with id '999999' not found"]
  }
}

---

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.