Edit templates

What this is about

All templates are in the database: the default per email and language, plus the wording of individual tenants. They can be changed at runtime, without a new delivery. Because an email is sent in the platform’s name, it is precisely defined who may change what.

The calls

An editor sees every template in the list, a tenant administrator only their tenant’s wording. The calls exist only if codamai.cias.notification.enabled, persistence: jpa and rest are switched on. Otherwise they answer 404, as if they did not exist.

Save a template

POST /cias/notification/templates
Authorization: Bearer <token of Anna, tenant-admin in nordbau>
{
  "key": "WELCOME",
  "locale": "de",
  "subject": "Willkommen bei Nordbau",
  "body": "Guten Tag,\n\nIhr Zugang ist bereit: ${loginUrl}\n\nIhr Nordbau-Team",
  "html": false
}

HTTP 200
{
  "id": "7d2c…",
  "key": "WELCOME",
  "tenantKey": "nordbau",
  "locale": "de",
  "subject": "Willkommen bei Nordbau",
  "body": "Guten Tag, …",
  "html": false,
  "updatedBy": "5c9e…",
  "updatedAt": "2026-10-01T10:15:00Z",
  "origin": "EDITED",
  "isDefault": false
}

A template is identified by email, tenant and language. Without a tenant there is exactly one per email and language: saving without tenantKey changes the default, it never creates a second one. Saving twice with the same features likewise results in one template.

The check

Who may do what, per installation

Which roles are editors is set by codamai.cias.notification.editor-roles, or the environment variable CIAS_NOTIFICATION_EDITOR_ROLES. The default is platform-admin,mail-template-admin. Which emails tenants may change is decided by each installation. There is deliberately no default for that: an installation that has not asked itself the question does not start.

mail-template-admin is a realm role, see The platform’s realm roles. It reaches the wording of every tenant and is therefore never granted within a tenant.

The list for tenants is an allow list, not a block list. New emails are therefore blocked for tenants at first. Why these in particular are not approved:

• VERIFY_EMAIL and PASSWORD_SETUP carry a link that opens an account. Whoever can reword them can write a convincing phishing email from the platform’s sender.
• ALREADY_REGISTERED may go to someone from an entirely different tenant.
• APPROVAL_PENDING and REJECTED word a decision. Whoever decides should not rewrite it afterwards.

The variants

What a template can do

Templates are written in FreeMarker, a template language. You can insert placeholders (${loginUrl}) and write simple conditions:

<#if passwordUrl?has_content>
Vergeben Sie jetzt Ihr Passwort: ${passwordUrl}
<#else>
Melden Sie sich an: ${loginUrl}
</#if>

Nothing more. Because people other than the developers write templates, FreeMarker is locked down: a template cannot create classes, cannot call methods and cannot reach the objects behind the values. It only sees the values of the context, plus ${application} and ${flow} in every email.

When saving, CIAS generates the template once as a trial, with the same locked-down setup and empty values for all placeholders. A template that cannot be generated this way is refused. Still check with a real email that the text arrives the way you want: placeholders with values sometimes behave differently from empty ones.

Errors at a glance

Pitfalls

Next

• How the right template is found
• Sending and branding
• The admin interface