Email templates & sender
Email templates that automations send to contacts, with merge tags, and the project's own SMTP sender.
Email templates are messages that automations send to contacts through the Send email
action. A template has a subject and a Markdown body, both with merge tags like {{contact.name}} and
{{order.serial}}. The available merge tags are listed in the user guide:
Email templates.
A project sends emails through its own SMTP sender, so that emails come from its domain. Without a sender, no
email is sent: automation runs fail with EMAIL_SENDER_NOT_CONFIGURED and
Send Email to Contact is rejected.
Emails are sent through automations, or to a single contact with Send Email to Contact.
Field types follow the field notation.
Access
Every endpoint on this page requires both the projects and email_templates OAuth scopes. The user must be a
member of the project, and the owner's subscription must be active. Otherwise the endpoint returns
404 RES_NOT_FOUND. The project owner bypasses permission checks.
| Permission | Grants |
|---|---|
can_view_email_templates |
Read templates and the sender settings |
can_edit_email_templates |
Create, update and delete templates; configure the sender |
Email Template Object
Email Template Structure
| Field | Type | Description |
|---|---|---|
| uuid | uuid | Template ID |
| name | string | Name for the team, 1–255 characters |
| subject | string | Subject line, 1–255 characters; merge tags work here |
| body | string | Message body in Markdown, with merge tags |
| created_at | ISO8601 datetime | When the template was created |
| updated_at | ISO8601 datetime | When the template was last changed |
Example Email Template
{
"uuid": "0199af6b-8293-74a5-b6c7-d8e9f0a1b2c3",
"name": "Order ready",
"subject": "Your order {{order.serial}} is ready",
"body": "Hello, {{contact.name}}!\n\nYour order **{{order.serial}}** is ready for pickup.\n\n— {{project.name}}",
"created_at": "2026-09-05T09:00:00.000Z",
"updated_at": "2026-09-05T09:00:00.000Z"
}
List Email Templates
GET /api/v1/projects/{project.uuid}/email-templates
Returns the project's templates, oldest first. Requires can_view_email_templates.
Get Email Template
GET /api/v1/projects/{project.uuid}/email-templates/{template.uuid}
Requires can_view_email_templates.
Create Email Template
POST /api/v1/projects/{project.uuid}/email-templates
Requires can_edit_email_templates.
| Field | Type | Description |
|---|---|---|
| name | string | 1–255 characters, trimmed |
| subject | string | 1–255 characters, trimmed |
| body | string | Not empty |
201 Created with {"uuid": "..."}.
subject and body are Handlebars templates and are checked when saved: a template that cannot be rendered (for example an
unclosed {{#if}}) is refused with 400 REQ_VALIDATION_FAILED, and errors names the field.
Modify Email Template
PATCH /api/v1/projects/{project.uuid}/email-templates/{template.uuid}
Updates any of name, subject, body. At least one must be present. 204 No Content. Requires
can_edit_email_templates. There is no PUT for email templates.
Delete Email Template
DELETE /api/v1/projects/{project.uuid}/email-templates/{template.uuid}
Deletes the template. Automations that use it fail with an error in their run history until another template is
chosen. 204 No Content. Requires can_edit_email_templates.
Email Sender
Email Sender Structure
| Field | Type | Description |
|---|---|---|
| from_name | string | Sender name |
| from_email | string | Sender address |
| reply_to | string | Reply-to address; empty for none |
| smtp_host | string | SMTP server |
| smtp_port | integer | SMTP port |
| smtp_secure | boolean | Use TLS from the start of the connection; usually true for port 465, false for 587 |
| smtp_user | string | SMTP username |
| track | boolean | Track opens and clicks: adds a tracking pixel and routes links through Configo |
| has_password | boolean | Whether a password is stored. The password itself is never returned |
| updated_at | ?ISO8601 datetime | When the settings were last saved |
Get Email Sender
GET /api/v1/projects/{project.uuid}/email-settings
Returns the sender, or null if the project has no sender configured. Requires
can_view_email_templates.
Set Email Sender
PUT /api/v1/projects/{project.uuid}/email-settings
Creates or replaces the sender. The password is stored encrypted. Requires can_edit_email_templates.
| Field | Type | Description |
|---|---|---|
| from_email | string | Valid email, up to 255 characters |
| smtp_host | string | 1–255 characters |
| from_name? | string | Up to 255 characters. Default "" |
| reply_to? | string | Valid email or "". Default "" |
| smtp_port? | integer | 1–65535. Default 587 |
| smtp_secure? | boolean | Default false |
| smtp_user? | string | Up to 255 characters. Default "" |
| smtp_password? | string | Up to 1024 characters. Required the first time. Omit or send "" later to keep the stored password |
| track? | boolean | Default false. If you turn it on, mention the tracking in your privacy policy |
{
"from_name": "Acme Windows",
"from_email": "[email protected]",
"smtp_host": "smtp.acme.example",
"smtp_port": 465,
"smtp_secure": true,
"smtp_user": "[email protected]",
"smtp_password": "app-password-here"
}
204 No Content. The settings are not tested on save; a wrong host or password shows up as failed automation runs.
An SMTP host that resolves to a private, loopback or link-local address is refused when sending.
Remove Email Sender
DELETE /api/v1/projects/{project.uuid}/email-settings
Removes the sender; the project cannot send emails until a new one is set. 204 No Content. Requires can_edit_email_templates.
Errors
| Status | Code | When |
|---|---|---|
| 400 | REQ_VALIDATION_FAILED |
The body does not match the schema, or a template cannot be rendered |
| 400 | REQ_NO_DATA_PROVIDED |
Modify Email Template: the body has no fields |
| 400 | EMAIL_SMTP_PASSWORD_REQUIRED |
Set Email Sender: no password sent and none stored |
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or email_templates |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role lacks the permission the endpoint needs |
| 404 | RES_NOT_FOUND |
The project or template does not exist |