SMTP (Email)

Klokk sends e-mails for invitations, password resets, decided requests, shift plans and other notifications. It sends them through an SMTP server of your choice.

Variables

Variable	Default	Description
SMTP_HOST	empty	Host name of the SMTP server. Empty switches e-mail off.
SMTP_PORT	587	587 for STARTTLS, 465 for implicit TLS.
SMTP_TLS	false	true = implicit TLS (port 465); false = STARTTLS (port 587).
SMTP_USER	—	User name for signing in to the server.
SMTP_PASS	—	Password; better as a file: SMTP_PASS_FILE=/run/secrets/smtp_pass.
SMTP_FROM	SMTP_USER	Sender address, such as [email protected] or with a display name: Klokk <[email protected]> (a plain address — a display name makes the server refuse the mail). Empty: the user name is used.

Like every variable, the password can come from a file (Docker secrets) — see environment variables.

Encryption and sign-in

Klokk always sends encrypted and signed in:

• with SMTP_TLS=false it starts with plain SMTP and switches to TLS with STARTTLS — a server without STARTTLS is refused;
• with SMTP_TLS=true the connection is TLS from the start (port 465).

The server’s certificate must be valid for SMTP_HOST. A mail relay without encryption or without sign-in does not work.

Examples

STARTTLS (port 587)

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASS_FILE=/run/secrets/smtp_pass
SMTP_FROM=[email protected]

Implicit TLS (port 465)

SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_TLS=true
SMTP_USER=[email protected]
SMTP_PASS_FILE=/run/secrets/smtp_pass

Tip

With Microsoft 365 or Google Workspace, use a mailbox or app password meant for SMTP sending; many providers block plain SMTP sign-in for normal accounts.

Without e-mail

Without SMTP_HOST Klokk runs fully, but sends nothing: the notification settings show “no SMTP”, password resets by e-mail are not available, and push notifications are the only way to be notified.

When something goes wrong

Klokk logs every attempt with recipient, mode (TLS/STARTTLS), server and sender, and the error, if any — for example smtp auth: … for wrong credentials, smtp starttls: … when the server offers no STARTTLS, or smtp mail from: … when the server refuses the sender.