Mail Server and Mail Templates

AI Knowledge Fabric can send e-mails. To do so, it needs a mail server (SMTP server) that you register under Admin → Mail Server (/admin/mail-server). The text of each mail is edited under Admin → Mail Templates (/admin/mail-templates).

Without a mail server, the platform sends no mails at all. Nothing else stops working, but users cannot reset a forgotten password by themselves.

1. Which mails the platform sends

The platform sends two kinds of mail. Each has its own template.

Mail Sent when

Test Mail

Sent from the Mail Server page to check the SMTP settings.

Password Reset

Sent when a user asks for a new password on the login page.

The password reset flow is described in Profile and Password Reset.

2. Permissions

Both pages use the platform settings permissions.

Permission Label in the role editor What it grants

CONFIG_VIEW

View LLM Config

Open Mail Server and Mail Templates and read the settings and templates

CONFIG_MANAGE

Manage LLM Config

Change and save the settings, send a test mail, edit, save and reset templates

With CONFIG_VIEW alone, all fields are read-only. The Save button is hidden and Send Test Mail is disabled. In the template list, the button on each row shows an eye (View) instead of a pencil (Edit).

The stored password is never shown, not even to users who may change the page. See Password below.

3. Setting up the mail server

Open Admin → Mail Server. The page has three areas: SMTP Server, Sender and Test Mail. Save is at the bottom. Changes apply to the next mail. No restart is needed.

SMTP Server

Field What it does

SMTP Host

The name or address of your mail server, for example smtp.example.com. Without a host, the platform sends no mails.

Port

The port of the mail server (1 to 65535). It is filled in for you when you pick an encryption — see below.

Encryption

How the connection to the mail server is protected. See Encryption.

Username

The login for the mail server. Leave it empty if the server accepts mails without a login.

Password

The password for that login. It is only saved together with a username. If you clear the username, the password is removed on save.

Password is never shown

After you save a password, the field stays empty and shows (saved). The stored password is never sent to the browser, so nobody can read it from the page.

  • Leave the field empty to keep the saved password. This also applies to Send Test Mail.

  • Type a new password to replace it. It is stored when you click Save.

  • Clear the Username to remove the password.

Sender

Field What it does

Sender Address

The address the mails come from, for example noreply@example.com. Users see it as the sender. Many mail servers only accept a sender address that belongs to your login. Required as soon as a host is set.

Sender Name

The name users see next to the sender address, for example AI Knowledge Fabric. Optional. Without it, users see only the address.

Platform URL

The address under which users open this application, for example kf.example.com. See below.

Platform URL

All links in mails start with the Platform URL. For example, the link in a password reset mail is the Platform URL followed by /reset-password?token=….

  • Set it to the address users type in their browser. If it points somewhere else, the links in mails lead to the wrong place or do not open at all.

  • Without it, "Forgot password" is not offered, even if the mail server works. A test mail can still be sent.

  • The platform never takes this address from the browser request. Only what you enter here is used.

The address must start with http:// or https:// and must contain a host name. It must not contain a query (?…) or a fragment (#…). A slash at the end is removed when links are built. A wrong value is refused with one of these messages:

Message Meaning

Must start with http:// or https://.

The address has no or another scheme

Must contain a host name.

The host part is missing

Must not contain a query (?…) or fragment (#…).

Remove everything from ? or # on

Not a valid URL.

The text is not an address at all

Saving

  • You can save a completely empty form. The platform then has no mail server and sends no mails. The message says so: "Saved. No mail server is configured, so the platform sends no mails."

  • As soon as SMTP Host or Sender Address is filled in, both are required, and the port must be between 1 and 65535. Otherwise the fields turn red and the message is "Fix the highlighted fields before saving."

  • After a successful save with a mail server, the message is "Saved. Send a test mail to check the settings."

4. Encryption and timeouts

The Encryption field has three choices:

Choice Port filled in When to use it

STARTTLS — encrypted, the usual choice

587

The default. The connection starts unprotected and is then switched to encryption.

SSL/TLS — encrypted from the start

465

For servers that expect encryption from the first moment.

None — not encrypted, only inside your own network

25

Only for a mail server in your own network. Login and mails travel unprotected.

When you change the encryption, the port changes with it, but only if the port still holds one of the three standard numbers (25, 587, 465). A port you entered yourself stays as it is.

STARTTLS never falls back to an unprotected connection. If the server does not offer encryption, sending fails. This protects the password and the mail content. With STARTTLS and SSL/TLS, the platform also checks that the server’s certificate matches the host name. Use the host name the certificate was issued for, not an IP address.

Each step of sending waits at most 15 seconds: building the connection, waiting for the server’s answer, and sending data. A server that does not answer makes sending fail after that time instead of hanging.

5. Sending a test mail

The Test Mail area sends the Test Mail template to the address in Recipient. The field is filled with your own e-mail address. You can enter any other address.

  • The test uses the values currently in the form, even before you save them. You can try a new setting without replacing a setting that works. Save only when the test succeeds.

  • The test needs SMTP Host, a valid Port and a valid Sender Address. If one is missing, the fields turn red and the message is "Fill in the highlighted fields first."

  • The text of the test mail comes from the saved Test Mail template.

  • While the mail is sent, the button shows Sending…​.

On success, the message is "Test mail sent to <address>. Check the inbox (and the spam folder)." On failure, the message is "Sending failed: …" followed by the reason from the mail server. See Troubleshooting.

6. Editing the mail templates

Open Admin → Mail Templates. The list shows one row per mail:

Column Content

Mail

The name of the mail

Sent when

When the platform sends it

Subject

The current subject

Last Changed

When the template was last saved

Click the pencil (or double-click the row) to open the editor. The dialog has two tabs:

  • Edit — the Subject and the Body (HTML). The body is written in HTML.

  • Preview — the mail as it will look, filled with sample values ("Rendered with sample values."). Scripts and forms in the template do not run in the preview.

The Variables panel on the right lists the placeholders this mail can use.

Placeholders

A word in double braces, like {{username}}, is a placeholder. When the mail is sent, the platform replaces it with the real value. Each mail has its own set of placeholders.

Test Mail

Placeholder Replaced with

{{recipient}}

Address the test mail was sent to

{{sentBy}}

Username of the admin who sent it

{{sentAt}}

Date and time of sending (in UTC)

{{smtpHost}}

Host and port of the SMTP server

{{platformUrl}}

Address of this application

Password Reset

Placeholder Replaced with Required

{{resetLink}}

Link to the page where the new password is set

Yes

{{expiresInMinutes}}

How long the link stays valid, in minutes

{{username}}

The user’s login name

{{firstName}}

The user’s first name

{{lastName}}

The user’s last name

{{platformUrl}}

Address of this application

A required placeholder must stay in the body. Without it, the mail is useless — a reset mail without its link cannot help anyone. It does not count if it is only in the subject.

If a user has no first or last name, that placeholder is replaced with nothing. For example, the default greeting then reads "Hello ,".

What is refused on save

Save checks the template. Problems are listed in red below the editor while you type. If you click Save with problems, the message is "The template cannot be saved. See the problems below the editor." The possible problems are:

Problem text What to do

The subject must not be empty.

Enter a subject

The body must not be empty.

Enter a body

Unknown variable {{name}}. Available: {{…}}, {{…}}.

The placeholder does not exist for this mail — often a typo. Use one from the list. This applies to the subject too.

The body must contain {{resetLink}} (link to the page where the new password is set).

Put the reset link back into the body

On success, the message is "Template saved".

How values are inserted

  • In the body, values are inserted as plain text. If a value contains HTML, for example a user name with <b>, the mail shows these characters as text. They do not change the layout and cannot add links. You do not need to protect anything yourself.

  • In the subject, line breaks inside a value are removed, so the subject always stays one line.

Reset to Default

Reset to Default loads the text the platform ships with into the editor. The message is "Default text loaded. Save to keep it." Nothing changes until you click Save. Cancel throws the loaded text away.

Every mail has a default text. The platform creates each template from its default on the first start. After that, it never changes a template on its own. A new version of the platform with a better default text therefore does not change your templates. Use Reset to Default if you want the new text. A new kind of mail added by an update gets its template on the next start.

7. Troubleshooting

Symptom Cause and fix

Mail Server / Mail Templates missing from the Admin menu

Your role lacks CONFIG_VIEW

All fields read-only, no Save button, Send Test Mail disabled

Your role lacks CONFIG_MANAGE

"Forgot password" is not shown on the login page

The mail server (host and sender address) or the Platform URL is missing, or login is set to SSO only. See Profile and Password Reset

Test mail fails after about 15 seconds

The server does not answer: wrong host or port, or a firewall blocks the connection

Test mail fails with STARTTLS

The server does not offer encryption on this port. Check the port (usually 587) or choose SSL/TLS with port 465. The platform never sends unencrypted with STARTTLS

Test mail fails with a certificate or host name error

The host name does not match the server’s certificate. Use the name the certificate was issued for, not an IP address

Test mail fails with an authentication error

Wrong Username or Password, or the server needs a login and Username is empty

Test mail fails because the sender is refused

Many servers only accept a Sender Address that belongs to the login

"Test mail sent", but nothing arrives

Check the spam folder. Check that the recipient address is right

The link in a reset mail does not open, or opens the wrong site

The Platform URL is wrong. Enter the address users type in their browser

The template cannot be saved

Read the red problem list below the editor

A new platform version did not change the mail text

Expected. Saved templates are never replaced. Use Reset to Default

Related