Mail dispatch

The global SMTP server connection is configured via the web interface. This connection is necessary if Relution is to actively send emails. These can be, for example, emails for a password reset, registration or notification. The connection of an SMTP server is optional.


Configuration

For system administrators, the SMTP server configuration is available in the Global organization under Settings → Email Configuration. It comprises the following fields:

  • Host and Port
  • Connection security: None, STARTTLS, STARTTLS (REQUIRETLS) or SSL/TLS. With STARTTLS, Relution switches to an encrypted connection if the server supports it; with STARTTLS (REQUIRETLS), sending fails if the server does not offer STARTTLS.
  • Use Extended Hello (EHLO): Required for STARTTLS and STARTTLS (REQUIRETLS).
  • HELO/EHLO local host name: If the field is left empty, the server’s external host name is used; if the external URL is an IP address, it is announced in the form [IP address].
  • Username and Password: If the password field is left empty when editing, the existing password is only kept for saving and for the test as long as Host, Port and Connection security are unchanged (see below).
  • Mail from: Required; this address is used as the sender of outgoing emails.

In the Test email configuration section, Send sends a test email using the currently entered, not yet saved values to the email address of the logged-in user. If no email address is stored for the logged-in account, the test fails. Like the configuration itself, the test is only available in the Global organization.

With an empty password field, Relution only uses the stored password if Host, Port and Connection security are unchanged compared to the saved configuration. An empty Port field counts as port 25. Changes to Username, Mail from, Use Extended Hello (EHLO) and HELO/EHLO local host name are not relevant. This rule applies to the test as of Relution 26.5.5 and, as of Relution 27.0.1, also to saving.

If one of the three values has been changed, Relution rejects saving and testing with an empty password field. Password becomes a required field, the placeholder and the hint “Leave empty to keep existing password” disappear, and the message “The connection endpoint has changed. Please enter the password or secret again.” appears below the field. In this case, the configuration is not saved. Once the password has been entered again, the configuration can be saved or the test can be repeated via Send. If no password is stored yet, this check does not apply.

As long as no SMTP server is configured, Relution shows system administrators in the Global organization the notification SMTP is not configured. With a configuration via the application.yml, it only disappears once the sender address is set via mail.smtp.from in addition to the mail server (see Additional mail session options →).


Precedence between web interface and application.yml

The configuration saved in the web interface takes precedence. The values from the application.yml or from environment variables are only used as long as no configuration is saved in the web interface. An existing configuration is removed in the Email server configuration category, section Clear configuration, via Clear; Relution then falls back to the application.yml.

Changes to the application.yml only take effect after the Relution server is restarted.


application.yml

relution:
  mail:
    username:
    password:
    host: localhost
    port: 25
  smtp:
    starttls: false
    ssl: false
    ehlo: true

The settings shown above are the default values if they are not configured. SMTP connectivity is tested as part of the server health check, which are displayed in the System Portal.

The former key ttls instead of starttls is still evaluated. If both ssl and starttls are true, Relution uses SSL/TLS.

Relution reads the mail configuration exclusively from relution.mail and relution.smtp. Entries under spring.mail are ignored. If the configuration is placed there, Relution tries to send mail via localhost on port 25.

Alternatively, the values can be set via environment variables, e.g. in a Docker installation:

Environment variableKey in application.yml
SMTP_HOSTrelution.mail.host
SMTP_PORTrelution.mail.port
SMTP_USERNAMErelution.mail.username
SMTP_PASSWORDrelution.mail.password
SMTP_TTLSrelution.smtp.starttls
SMTP_SSLrelution.smtp.ssl
SMTP_EHLOrelution.smtp.ehlo

A value set explicitly in the application.yml takes precedence over the environment variable.


Additional mail session options

Further options can be passed directly to the mail library (Jakarta Mail) via relution.mail.properties. The entries are applied unchanged and override the values set by Relution. They only take effect as long as the configuration comes from the application.yml, i.e. no configuration is saved in the web interface.

relution:
  mail:
    host: smtp.example.com
    port: 587
    username: "relay@example.com"
    password: "xxx"
    properties:
      "[mail.smtp.from]": "mdm@example.com"
      "[mail.smtp.starttls.required]": "true"
      "[mail.smtp.ssl.trust]": "smtp.example.com"
  smtp:
    starttls: true
    ssl: false
    ehlo: true

The keys contain dots and are therefore enclosed in square brackets and quotes. Commonly used options:

OptionEffect
mail.smtp.fromSender address. If not set, Relution derives an address from the domain of the external server URL (no-reply+relution@<domain>, e.g., no-reply+relution@example.com for mdm.example.com).
mail.smtp.localhostHost name announced in the EHLO command. If not set, the host name of the external server URL is used.
mail.smtp.starttls.requiredAborts sending if the server does not offer STARTTLS.
mail.smtp.ssl.trustHosts whose certificate is trusted without validation. Helps with mail servers that present an incomplete certificate chain.

mail.smtp.ssl.trust should contain the specific host name of the mail server. The value * trusts every certificate of every server. The better solution remains to add the certificate of the issuing certificate authority to the truststore.

If the log level for io.relution.setting.system.email.SystemEmailConfigurationService is set to DEBUG, Relution writes the complete SMTP communication to standard output for every message sent (with Docker in docker logs), not necessarily to the Relution log file. For the test email under Test email configuration, the setting takes effect immediately. For regular sending, it only takes effect after the email configuration has been saved again or the server has been restarted. This also applies when resetting to INFO. Set log level →


Amazon Simple Email Service (SES) SMTP

The recommended settings for connecting to Amazon SES are as follows:

relution:
  mail:
    username: ABCDEFGHIJKLMNOPQ123
    password: "abcdefghijklmnopqrstuvwxyz/BASE64+1234567890"
    host: email-smtp.eu-central-1.amazonaws.com
    port: 587
  smtp:
    starttls: true
    ssl: false
    ehlo: true

The SMTP parameters username and password must be an AWS access key and a secret key of an IAM user with AmazonSesSendingAccess permissions, which grants ses:SendRawEmail rights. The correct region must be specified as part of host. These settings can be found on the SMTP Settings page of the SES service in the AWS console.


Microsoft Office365 SMTP

The recommended settings to be able to send mail via Office 365 are these:

The Mail from address under Settings → Email Configuration must match the account’s username. If the configuration is made via the application.yml, the sender address is set via mail.smtp.from (see Additional mail session options →). SMTP AUTH must be enabled for the account.

relution:
  mail:
    username: "email@somewhere.com"
    password: "xxx"
    host: smtp.office365.com
    port: 587
  smtp:
    starttls: true
    ssl: false
    ehlo: true

How helpful was this article?