Documentation / Email templates & sender

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