SMTP email

ASAB IRIS can send email notifications through an SMTP server.

Use SMTP when the organization already provides a mail relay or when Microsoft 365 email is not used in the deployment.

Note

If SMTP is configured, IRIS uses SMTP for email. If SMTP is not configured and Microsoft 365 email is configured, IRIS uses Microsoft 365.

Prerequisites

Before configuring SMTP, make sure that:

• the organization provides an SMTP server or mail relay
• the LogMan.io server can connect to the SMTP server on the configured port
• the required SMTP TLS mode is known, either implicit TLS or STARTTLS
• SMTP credentials are available, if the server requires authentication
• the configured sender address is allowed to send through the SMTP server
• the CA certificate chain is available if the SMTP server uses an internal certificate authority
• HTTP CONNECT proxy details are available if outbound SMTP traffic must go through a proxy

Required configuration fields

Field	Description
host	SMTP server hostname or IP address.
port	SMTP server port. Common values are 465 for implicit TLS and 587 for STARTTLS.
from	Default sender email address.

Authentication fields are required when the SMTP server requires login:

Field	Description
user	SMTP username.
password	SMTP password.

TLS fields control how IRIS connects to the SMTP server:

Field	Description
ssl	Set to yes for implicit TLS, commonly on port 465.
starttls	Set to yes for STARTTLS, commonly on port 587.
validate_certs	Set to yes to verify the SMTP server certificate. This is recommended for production.
cert_bundle	Optional path to a CA or certificate-chain PEM file for internal certificate authorities.

Warning

Do not enable both ssl and starttls at the same time.

Optional configuration fields

Field	Description
subject	Default email subject used when a notification does not provide one.
proxy_host	HTTP CONNECT proxy hostname.
proxy_port	HTTP CONNECT proxy port.
proxy_user	Optional proxy username.
proxy_password	Optional proxy password.
proxy_connect_timeout	Proxy connection timeout in seconds.

Proxy settings are needed only when the LogMan.io server must reach the SMTP server through an HTTP CONNECT proxy.

Configuration sample

Edit model.yaml to configure the asab-iris service:

/Site/model.yaml

define:
  type: rc/model

services:
  asab-iris:
    instances:
      - node1
    asab:
      config:
        smtp:
          host: smtp.example.com
          port: 587
          user: "{{SMTP_USER}}"
          password: "{{SMTP_PASSWORD}}"
          from: "noreply@example.com"
          ssl: no
          starttls: yes
          validate_certs: yes
          cert_bundle: ""

Setup instructions

1. Get the SMTP server details from the mail administrator:
2. hostname
3. port
4. TLS mode
5. username and password, if authentication is required
6. sender address
7. Confirm that the LogMan.io server can reach the SMTP server.
8. Choose the TLS mode:
9. use ssl: yes and starttls: no for implicit TLS on port 465
10. use ssl: no and starttls: yes for STARTTLS on port 587
11. If the SMTP server uses an internal certificate authority, copy the CA chain PEM file to the LogMan.io environment and configure cert_bundle.
12. Store SMTP credentials in Vault or in the deployment secret store used by the LogMan.io installation.
13. Update /Site/model.yaml.
14. Apply the model from the Library, or run the deployment apply command used by the installation.
15. Send a test email notification.

Verify the configuration

The configuration is ready when:

• ASAB IRIS starts without SMTP configuration errors
• a test email is delivered to the expected recipient
• the message is sent from the configured from address
• TLS certificate validation succeeds, if validate_certs is enabled
• attachments are delivered, if the notification includes attachments

Common configurations

STARTTLS on port 587

/Site/model.yaml

services:
  asab-iris:
    asab:
      config:
        smtp:
          host: smtp.example.com
          port: 587
          user: "{{SMTP_USER}}"
          password: "{{SMTP_PASSWORD}}"
          from: "noreply@example.com"
          ssl: no
          starttls: yes
          validate_certs: yes
          cert_bundle: ""

Implicit TLS on port 465

/Site/model.yaml

services:
  asab-iris:
    asab:
      config:
        smtp:
          host: mail.internal.example
          port: 465
          user: "{{SMTP_USER}}"
          password: "{{SMTP_PASSWORD}}"
          from: "noreply@example.com"
          ssl: yes
          starttls: no
          validate_certs: yes
          cert_bundle: "/etc/ssl/internal-ca.pem"

SMTP through an HTTP CONNECT proxy

/Site/model.yaml

services:
  asab-iris:
    asab:
      config:
        smtp:
          host: mail.internal.example
          port: 465
          user: "{{SMTP_USER}}"
          password: "{{SMTP_PASSWORD}}"
          from: "noreply@example.com"
          ssl: yes
          starttls: no
          validate_certs: yes
          cert_bundle: "/etc/ssl/internal-ca.pem"
          proxy_host: proxy.example.com
          proxy_port: 3128
          proxy_user: "{{SMTP_PROXY_USER}}"
          proxy_password: "{{SMTP_PROXY_PASSWORD}}"
          proxy_connect_timeout: 10

Email templates

Email templates must be stored in the /Templates/Email/ directory in the Library.

For more information about email notifications and templates, see:

• Email notifications
• Creating email templates