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. Minimum 3 characters. If omitted, auto-generated as `API Template {timestamp}`.
`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	Language code (e.g. `en`, `fr`) or numeric language ID. Defaults to `en`.
`group`	string or integer	No	Group name or group ID to assign the template to.

*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.

Response

On success, the API returns 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 fewer than 3 characters or missing.
`The field 'html' may not be longer than 200kB`	HTML content exceeded the 200 KB limit.
`Invalid 'language'`	The `language` value was not a recognised language code or ID.
`Invalid 'group'`	The `group` value did not match a valid group of type `message_template`.
`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'"],
    "allowed_values": {
      "language": { "1": "English", "2": "French" }
    }
  }
}

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.

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