SMTP - Authelia — ContextQMD

Variables

Some of the values within this page can automatically be replaced with documentation variables.

Configuration

yaml

notifier:
  disable_startup_check: false
  smtp:
    address: 'smtp://127.0.0.1:25'
    timeout: '5s'
    username: 'test'
    password: 'password'
    sender: "Authelia <admin@{{< sitevar name="domain" nojs="example.com" >}}>"
    identifier: 'localhost'
    subject: "[Authelia] {title}"
    startup_check_address: 'test@{{< sitevar name="domain" nojs="example.com" >}}'
    disable_require_tls: false
    disable_starttls: false
    disable_html_emails: false
    tls:
      server_name: 'smtp.{{< sitevar name="domain" nojs="example.com" >}}'
      skip_verify: false
      minimum_version: 'TLS1.2'
      maximum_version: 'TLS1.3'
      certificate_chain: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      private_key: |
        -----BEGIN PRIVATE KEY-----
        ...
        -----END PRIVATE KEY-----

Options

This section describes the individual configuration options.

address

Configures the address for the SMTP Server. The address itself is a connector and the scheme must be smtp, submission, or submissions. The only difference between these schemes are the default ports and submissions requires a TLS transport per SMTP Ports Security Measures, whereas submission and smtp use a standard TCP transport and typically enforce StartTLS.

Examples:

yaml

notifier:
  smtp:
    address: 'smtp://127.0.0.1:25'

yaml

notifier:
  smtp:
    address: 'submissions://[fd00:1111:2222:3333::1]:465'

timeout

{{< confkey type="string,integer" syntax="duration" default="5 seconds" required="no" >}}

The SMTP connection timeout.

username

The username sent for authentication with the SMTP server. Paired with the password.

password

The password paired with the username sent for authentication with the SMTP server.

It's strongly recommended this is a Random Alphanumeric String with 64 or more characters and the user password is changed to this value.

sender

The sender is used to construct both the SMTP command MAIL FROM and to add the FROM header. This address must be in RFC5322 format. This means it must one of two formats:

[email protected]
John Smith <[email protected]>

The MAIL FROM command sent to SMTP servers will not include the name portion, this is only set in the FROM as per specifications.

identifier

The name to send to the SMTP server as the identifier with the HELO/EHLO command. Some SMTP providers like Google Mail reject the message if it's localhost.

subject

{{< confkey type="string" default="[Authelia] {title}" required="no" >}}

This is the subject Authelia will use in the email, it has a single placeholder at present {title} which should be included in all emails as it is the internal descriptor for the contents of the email.

startup_check_address

{{< confkey type="string" default="[email protected]" required="no" >}}

Authelia checks the SMTP server is valid at startup, one of the checks requires we ask the SMTP server if it can send an email from us to a specific address, this is that address. No email is actually sent in the process. It is fine to leave this as is, but you can customize it if you have issues or you desire to.

disable_require_tls

{{< callout context="danger" title="Security Note" icon="outline/alert-octagon" >}} Enabling this value will result in all emails being sent in the clear and will leak values which have a critical security impact. This is almost certainly an indication attackers would be able to easily perform a phishing attack using your SMTP server and Authelia SMTP credentials. {{< /callout >}}

For security reasons the default settings for Authelia require the SMTP connection is encrypted by TLS. See security for more information. This option disables this measure but this is highly discouraged and not a supported configuration.

disable_starttls

Some SMTP servers ignore SMTP specifications and claim to support STARTTLS when they in fact do not. For security reasons Authelia refuses to send messages to these servers. This option disables this measure and is enabled AT YOUR OWN RISK. It's strongly recommended that instead of enabling this option you either fix the issue with the SMTP server's configuration or have the administrators of the server fix it. If the issue can't be fixed via the SMTP server configuration we recommend lodging an issue with the authors of the SMTP server.

See security for more information.

disable_html_emails

This setting completely disables HTML formatting of emails and only sends text emails. Authelia by default sends mixed emails which contain both HTML and text so this option is rarely necessary.

tls

If defined this option controls the TLS connection verification parameters for the SMTP server.

By default Authelia uses the system certificate trust for TLS certificate verification of TLS connections and the certificates_directory global option can be used to augment this.

Using Gmail

You need to generate an app password in order to use Gmail SMTP servers. The process is described here.

yaml

notifier:
  smtp:
    address: 'submission://smtp.gmail.com:587'
    username: '[email protected]'
    # Password can also be set using a secret: https://www.authelia.com/configuration/methods/secrets/
    password: 'yourapppassword'
    sender: 'admin@{{< sitevar name="domain" nojs="example.com" >}}'