Skip to main content
POST
Creates a new email template with either HTML or JSON content. Provide html for raw HTML templates or json for visual editor (Topol) templates — these fields are mutually exclusive. The template is automatically assigned a URL-friendly slug based on its name. You can optionally assign it to a specific project and folder using project_id and folder_id. If omitted, the template is added to your team’s default project.

​
Choosing the mode

purpose decides which of Lettr’s two modes the template belongs to:
  • transactional (default) — receipts, password resets, alerts; the templates you send single emails with
  • campaign — marketing content, and the only kind a campaign can pick
purpose cannot be changed afterwards. It is not accepted by Update Template — sending it there returns 200 and leaves the mode untouched. A newsletter created without purpose becomes a transactional template that campaigns cannot use, and the only remedy is the Copy to Marketing action in the app.If the template is going to an audience rather than to one person, pass purpose: "campaign" now.
Folders are mode-scoped, so folder_id must name a folder of the same mode as purpose; a folder of the other mode returns 422. Leave folder_id out and the template goes to the main folder of its mode, so a campaign template appears in the marketing module and the campaign picker straight away. Use List Folders to find a folder — it is the only endpoint that returns folder IDs, and it reports each folder’s mode.

​
Validation

json must be a Topol editor design. JSON that isn’t one is rejected with 422 instead of being saved as a template that breaks when opened in the editor.

​
Preparation

Templates created from json are rendered by a background job, so the response comes back with preparation_status: "pending" and no HTML yet. Rendering in the background means large imports don’t time out. It normally settles within seconds, and ends as ready or failed — poll Get Template until preparation_status is ready before sending. Templates created from raw html are ready immediately.

Authorizations

​
Authorization
string
header
required

API key for authentication

Body

application/json

Request to create a new email template. Provide either html for custom HTML templates or json for Topol visual editor templates.

​
name
string
required

Name of the template

Maximum string length: 255
Example:

"Welcome Email"

​
project_id
integer

Project ID to create the template in. If not provided, uses the team's default project.

Required range: x >= 1
Example:

5

​
folder_id
integer

Folder ID to create the template in. Must belong to the same module as purpose. If not provided, the first folder of that module is used, and one is created when the project has none.

Required range: x >= 1
Example:

10

​
html
string

HTML content for custom HTML templates. Required if json is not provided. Mutually exclusive with json.

Example:

"<html><body><p>Hello {{NAME}}!</p></body></html>"

​
json
string

JSON content for Topol visual editor templates. Required if html is not provided. Mutually exclusive with html.

Example:

"{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}"

​
purpose
enum<string>
default:transactional

Module the template belongs to. transactional templates are the ones you send single emails with; campaign templates are the ones the campaign builder can pick. Defaults to transactional.

Available options:
transactional,
campaign
Example:

"campaign"

Response

Template created successfully

Response after successfully creating a template

​
message
string
required

Human-readable response message

Example:

"Template created successfully."

​
data
object
required

View of a newly created template