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