Template API - Insert

Use this endpoint to create a new email template in your account.

---

Endpoint

POST https://e1.envoke.com/v2/templates

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

Field	Type	Required	Description
name	string	No	Template name, at least 3 characters when sent. If omitted, the template is named API Template {Y-m-d H:i:s} from the time of the request. Names are not unique.
html	string	Yes*	Full HTML content for the template. Maximum 200 KB.
template_id	integer	Yes*	ID of an existing template or message to copy HTML from.
language	string or integer	No	en or fr, or the language ID 1 or 3. Defaults to en.
group	string or integer	No	Group name or group ID to assign the template to.
status	string	No	published or unpublished. Defaults to published.

*Either html or template_id must be provided — but not necessarily both. If template_id is given, its HTML is copied into the new template.

Note: status defaults to published if not specified on create. Pass "unpublished" to create the template in a draft state. An HTML template that contains the <meta name="TEMPLATE_VERSION" tag opens in Envoke’s drag-and-drop editor; see Making HTML Editable.

---

Response

On success, the API returns HTTP 200 (not 201) with the newly created template object:

{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "42",
    "external_id": "a1b2c3d4e5f6",
    "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6",
    "name": "Welcome Email",
    "status": "published",
    "language": "en",
    "group": "Onboarding",
    "create_time": "2026-04-11 09:00:00",
    "modified_time": "2026-04-11 09:00:00"
  }
}

result_data.id is the Envoke template ID. Store this if you need to update or delete the template later.

The html field is not included in the create response. To retrieve the HTML, use a separate GET /v2/templates/{id}?include_html=1 request.

---

Validation Errors

If the request body is invalid, the API returns a 400 response:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "One of the fields 'template_id' or 'html' must be provided in order to create a template"
    ]
  }
}

Common validation errors:

Error	Cause
Request body may not be empty	No JSON body was provided.
One of the fields 'template_id' or 'html' must be provided in order to create a template	Neither html nor template_id was included.
The field 'name' must be at least 3 characters long	name was sent with fewer than 3 characters, including "". A missing name is not an error.
The field 'html' may not be longer than 200kB	HTML content exceeded the 200 KB limit.
Invalid 'language': '{value}'	The language value was not a recognised language code or ID.
Invalid 'group': '{value}'	The group value did not match a template group.
Invalid 'status': '{value}'	status was not published or unpublished.
Nothing found for 'template_id': {id}	The template_id does not exist or is not accessible to your account.
'{field}' is not a valid field	An unrecognised field was included in the request body.

Some errors include an allowed_values object:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Invalid 'language': 'de'"],
    "allowed_values": {
      "language": { "1": "en", "3": "fr" }
    }
  }
}

---

Examples

Create with inline HTML

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Email", "html": "<html><body><h1>Welcome!</h1></body></html>"}' \
  "https://e1.envoke.com/v2/templates"

Create with a group and language

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bienvenue", "html": "<html><body><h1>Bienvenue!</h1></body></html>", "language": "fr", "group": "Onboarding"}' \
  "https://e1.envoke.com/v2/templates"

Create by copying an existing template

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Email (Copy)", "template_id": 10}' \
  "https://e1.envoke.com/v2/templates"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.