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.
By default emails go out from Configo's mailbox. A project can configure its own SMTP sender so that emails come from its domain.
The API cannot send an email directly: sending happens only through automations.
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": "..."}.
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 sends from Configo's mailbox. 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; emails go out from Configo's mailbox again. 204 No Content. Requires can_edit_email_templates.
Errors
| Status | Code | When |
|---|---|---|
| 400 | REQ_VALIDATION_FAILED |
The body does not match the schema |
| 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 |