Knowledge base / Setup

Setting up mail

SMTP settings for reminders, invitations and reports, with a test.

Without mail Kontris only logs reminders. With mail, reminders, escalations, task summaries, reports and invitations go to the users.

Settings

Mail server with authentication (common):

MAIL_ENABLED=true
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USER=contracthub@example.com
SMTP_PASSWORD=<password>
SMTP_FROM=Kontris <contracthub@example.com>

Internal relay without authentication:

MAIL_ENABLED=true
SMTP_HOST=relay.example.local
SMTP_PORT=25
SMTP_SECURITY=starttls
SMTP_FROM=Kontris <contracthub@example.com>
SMTP_SECURITY Meaning Usual port
tls Encrypted from the first byte 465
starttls Upgrade to TLS is mandatory, otherwise the connection is dropped 587 or 25
none Unencrypted, only for a relay without authentication 25

Kontris never falls back to plain text and always verifies certificates. Many servers only accept the address of the authenticated account as sender.

Certificate from your own certificate authority

SMTP_TLS_CA_FILE=/certs/mail-ca.pem
# only if the name in the certificate differs from SMTP_HOST
SMTP_TLS_SERVERNAME=relay.example.local
    volumes:
      - ./mail-ca.pem:/certs/mail-ca.pem:ro

Testing

After the restart (docker compose up -d --force-recreate contracthub):

# check connection and authentication only
docker compose exec contracthub node dist/mail-test.js
# send a test mail
docker compose exec contracthub node dist/mail-test.js you@example.com

Without the command line: Administration → Notifications → Send test mail shows the mail server’s answer directly.

When the check runs

The daily deadline check runs at 6 a.m. in the time zone TZ. Change the time with NOTIFY_CRON. If the server was off at that time, the run is made up at the next start. A second run on the same day sends nothing twice.

Common errors

Message Cause Remedy
Invalid login Wrong user or password, or SMTP AUTH is blocked for the mailbox Check the credentials. With Microsoft 365 allow “Authenticated SMTP” on the mailbox
UNABLE_TO_GET_ISSUER_CERT_LOCALLY, self-signed certificate Certificate from your own certificate authority Set SMTP_TLS_CA_FILE
Hostname/IP does not match certificate's altnames The name in the certificate differs Set SMTP_TLS_SERVERNAME
ECONNREFUSED, timeout Port blocked Check the firewall
Status “Logged” MAIL_ENABLED=false Switch mail on

Links in mails are built from APP_BASE_URL. The value must be the address at which users actually reach Kontris.

As of 2026-11-15 · Stuck? Write to us