# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
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

```bash
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

```bash
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](https://developers.envoke.com).*