---
title: create_template
slug: docs/createtemplate
docTags: 
createdAt: 2026-07-07T18:35:22.541Z
---

Creates an email template in a project and stores its subject and HTML body.

A template goes under a category, so `create_template` requires a `cat_id` - create the category first with `create_category`, or reuse an existing one. You can let the system generate the template id, or supply your own with `template_id` (see section below on choosing a template id). The caller may only create templates in a project their account owns.

## Basic structure

Each call to the API requires `action` and a `group_id`.

| Name       | Type    | Required | Description                                                                                                                        |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `action`   | string  | true     | For this call, `create_template`.                                                                                                  |
| `group_id` | integer | true     | Designates which project the template belongs to. The `Api-Id` in the header must be part of the organization that owns the group. |
| `doc`      | array   | true     | see doc parameters below                                                                                                           |

## Doc Parameters

| Name          | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `cat_id`      | string | true     | The category id the template goes under (from `create_category`). |
| `name`        | string | true     | Template name, shown in the app.                                  |
| `subject`     | string | true     | Email subject line.                                               |
| `html`        | string | true     | The email body HTML.                                              |
| `template_id` | string | false    | A template id you choose. If omitted, the system generates one.   |



## Example call

:::CodeblockTabs
```curl
curl -X POST "https://www.regpack.com/reg/api2/emails/" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Api-Id: 15263" \
     -H "Api-user: api_admin@regpacks.com" \
     -H "Api-Token: cd2e514f-7gab-3cde-62fg-51abcd4e7362" \
     -d '{
    "action": "create_template",
    "group_id": 100909072,
    "doc": {
        "cat_id": "112481",
        "name": "Welcome email",
        "subject": "Welcome to the program",
        "html": "<h1>Welcome</h1><p>We are glad you are here.</p>",
        "template_id": "100909072_welcome"
    }
}'
```

```python
import requests
import json
emails_endpoint = "https://www.regpack.com/reg/api2/emails/"
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Id": "15263",
    "Api-user": "api_admin@regpacks.com",
    "Api-Token": "cd2e514f-7gab-3cde-62fg-51abcd4e7362",
}
payload = {
    "action": "create_template",
    "group_id": 100909072,
    "doc": {
        "cat_id": "112481",
        "name": "Welcome email",
        "subject": "Welcome to the program",
        "html": "<h1>Welcome</h1><p>We are glad you are here.</p>",
        "template_id": "100909072_welcome",
    },
}
create_template_json = json.dumps(payload)
create_template_response = requests.post(url=emails_endpoint,
                                         data=create_template_json,
                                         headers=headers,
                                         timeout=10)
```
:::

## Example response

The response returns the template's `template_id` - always reference this value going forward, even if it differs from the one you requested - and existed, which is true only when no `template_id` was supplied and a template with the same name already existed in the project (that existing template is returned unchanged).

```json
{
    "success": true,
    "template_id": "100909072_welcome",
    "existed": false
}
```

## Choosing `template_id`

A template id is **globally unique** across all projects. To make sure one project can never overwrite another project's template, a supplied `template_id` is handled as follows:

| Your `template_id`…                       | Result                                                                                                                                                            |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| already exists **in this same project**   | The template is **edited**—its name, category, subject, and HTML are updated.                                                                                     |
| is **not used by any project**            | The template is **created with exactly that id**.                                                                                                                 |
| already exists **in a different project** | Your id is **rejected** to protect the other project. The template is still created, but under a **system-generated id**, and the response tells you (see below). |
| **omitted**                               | The system generates the id. The call is idempotent by `name`: sending the same `name` again returns the existing template.                                       |

### Response when the requested id was rejected

```json
{
    "success": true,
    "template_id": "100909072_200145",
    "existed": false,
    "id_rejected": true,
    "requested_template_id": "100909072_welcome",
    "warning": "Requested template_id '100909072_welcome' is already in use in another project; created with auto-generated id '100909072_200145' instead."
}
```

| Field                   | Type   | Meaning                                                     |
| ----------------------- | ------ | ----------------------------------------------------------- |
| `id_rejected`           | bool   | Present and `true` when the requested id could not be used. |
| `requested_template_id` | string | The id you asked for.                                       |
| `warning`               | string | Human-readable explanation.                                 |