create_template

7 min

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

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: [email protected]" \
     -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"
    }
}'

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

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

{
    "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.