Sending and branding

What this is about

Between “a registration needs an email” and “the email is in the inbox” there are three steps. The module that needs the email says what should be said. cias-notification decides how: it finds the template, fills it in and sends it.

From occasion to email

An email comes about

1

CIAS
the registration puts the order together: which email, to whom, language, tenant, application, flow and the context with the placeholders
2

Hook
every registration hook may add to the order, for example brand name and logo
3

CIAS
finds the right template and fills it in

see How the right template is found
4

CIAS→Email
sends the finished email via SMTP, or only writes the subject to the log

Result: Email sent

The ways of sending

How an email leaves the house

SMTPLognotification switched off

When: codamai.cias.notification.mail: smtp

CIAS sends through the mail server that Spring Boot knows from spring.mail.host, port, username and password. The sender is in codamai.cias.notification.mail.from; without it the application does not start. An HTML email goes out in two parts: HTML and a plain text version derived from it. A plain text email goes out as one part.

Result: Email in the inbox. If the server fails, the call that triggered the email fails. Only for the welcome email is the registration still finished

When: codamai.cias.notification.mail: log

Nothing is sent. For every email CIAS writes a warning with the subject to the log. Not the text: it may contain a one-time link. Meant for development.

Result: Every flow reports success, but nobody gets an email

When: codamai.cias.notification.enabled: false

The module does nothing. Whoever wants to send an email gets an error, instead of the email silently disappearing. The template administration answers 404.

Result: error when trying to send

The settings

Setting	Meaning	standalone CIAS	in the hub backend
`codamai.cias.notification.enabled`	module on or off	`true`	follows `CIAS_REGISTRATION`
`codamai.cias.notification.mail`	`smtp` or `log`	`smtp`	`CIAS_MAIL`, default `log`
`codamai.cias.notification.mail.from`	sender address, only for `smtp`	from the environment	`CODAMAI_CIAS_NOTIFICATION_MAIL_FROM`
`spring.mail.*`	the mail server	from the environment	`SPRING_MAIL_HOST`, `_PORT`, `_USERNAME`, `_PASSWORD`
`codamai.cias.notification.persistence`	`jpa`: all templates in the system database, copied from what ships on start	`jpa`	`jpa`
`codamai.cias.notification.editor-roles`	who may change every template (environment `CIAS_NOTIFICATION_EDITOR_ROLES`)	`platform-admin,mail-template-admin`	platform administrator roles, plus the same setting
`codamai.cias.notification.rest`	template administration over HTTP	`true`	follows `CIAS_REGISTRATION`
`codamai.cias.notification.fallback-language`	language of the last level of the search	German	German

Without persistence: jpa there are no templates in the database and nothing can be edited. The shipped ones still apply, emails still go out.

Branding: logo and colors as data

A customer wants their emails with their own name, logo and colors. There are two ways:

Two ways to an own look

branding through the contextbranding through an own template

When: Many customers, each with their own name and logo, but the same wording.

A registration hook adds to the context in beforeNotification, for example brandName, logoUrl and primaryColor, matching the tenant. One template per email and language reads these values. So there are no hundred copies of the same email that drift apart over time.

Result: one wording, many brands

When: A customer wants different words, not just a different logo.

Save a template for this tenant, see Edit templates. It applies only to this customer, in every product.

Result: own wording for one customer

The shipped templates are plain text and read no brand values. Whoever uses branding through the context therefore changes the default so that it inserts brandName and the other values. Emails of user management (PASSWORD_SETUP) do not pass through registration hooks; they get branding only through a template.

What does the customer want?

Different look?	Different words?	Way
yes	no	context through a hook, one shared template
–	yes	own template for the tenant
no	no	do nothing, the installation's template applies

Languages

Every email has a language. For registration it comes from the request (locale); if none is given it is German. CIAS ships every template in German and English. For every further language you save your own templates. If a language is missing, the email goes out in the fallback language.