Skip to content

Email

import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs";

This page covers both configuring authentik to send email and testing that email delivery is working.

Global email settings are used for administrator notifications, release and configuration alerts, notification rules, and any Email stage configured to use global settings.

Email stages can be configured to use their own stage-specific SMTP settings if you need them to send mail through a different server than the one used by the rest of authentik.

:::warning Some hosting providers block outgoing SMTP ports, in which case you will need to host an SMTP relay on a different port with a different provider. :::

Before you begin

Have the following values ready:

  • SMTP server hostname or IP address
  • SMTP port
  • SMTP server username and password, if authentication is required
  • The sender address for AUTHENTIK_EMAIL__FROM
  • The TLS mode required by your provider

Configure global email settings

Set the global SMTP configuration in your deployment, then redeploy authentik.

Follow your mail provider's documentation and configure TLS mode as follows:

  • STARTTLS, also called explicit TLS, often uses port 587. Set AUTHENTIK_EMAIL__USE_TLS=true and leave AUTHENTIK_EMAIL__USE_SSL=false.
  • SSL or implicit TLS often uses port 465. Set AUTHENTIK_EMAIL__USE_SSL=true and leave AUTHENTIK_EMAIL__USE_TLS=false.
  • Plain SMTP without TLS should leave both settings disabled.

Never enable USE_TLS and USE_SSL at the same time. In the Helm chart, apply the same rules to email.use_tls and email.use_ssl.

<Tabs groupId="deployment" defaultValue="docker" values={[ { label: "Docker", value: "docker" }, { label: "Kubernetes", value: "kubernetes" }, ]}

To configure global email settings, append the following block to your .env file:

# SMTP server
AUTHENTIK_EMAIL__HOST=localhost
AUTHENTIK_EMAIL__PORT=25
# Optionally authenticate (don't add quotation marks to your password)
AUTHENTIK_EMAIL__USERNAME=
AUTHENTIK_EMAIL__PASSWORD=
# STARTTLS / explicit TLS, usually on port 587
AUTHENTIK_EMAIL__USE_TLS=false
# Implicit TLS/SSL on the SMTP connection (`USE_SSL` is the variable name), usually on port 465
AUTHENTIK_EMAIL__USE_SSL=false
AUTHENTIK_EMAIL__TIMEOUT=10
# Sender email address; verify that the domain is valid.
AUTHENTIK_EMAIL__FROM=authentik@example.com

To configure global email settings, append the following block to your values.yaml file:

# add this block under the `authentik:` block in your values.yaml file
# authentik:
email:
    # -- SMTP server from which emails are sent by authentik
    host: ""
    port: 25
    # -- Optional SMTP authentication credentials. Leave empty to disable authentication.
    username: ""
    # -- Optional SMTP authentication credentials. Leave empty to disable authentication.
    password: ""
    # -- STARTTLS / explicit TLS, usually on port 587.
    use_tls: false
    # -- Implicit TLS/SSL, usually on port 465 (`use_ssl` is the setting name).
    use_ssl: false
    # -- Connection timeout in seconds
    timeout: 10
    # -- Email 'from' address can either be in the format "foo@bar.baz" or "authentik <foo@bar.baz>"
    from: "authentik@example.com"

When to use stage-specific settings

Email stages can either:

  • use the global SMTP settings described above, or
  • use their own stage-specific SMTP host, port, credentials, and TLS settings

Test email delivery

After configuring SMTP, send a test message from the authentik server:

ak test_email <to_address>

To test a specific Email stage instead of the global settings, include -S:

ak test_email <to_address> [-S <stage_name>]

<Tabs groupId="deployment" defaultValue="docker" values={[ { label: "Docker", value: "docker" }, { label: "Kubernetes", value: "kubernetes" }, ]}

To run this command with Docker Compose:

docker compose exec worker ak test_email [...]

To run the command in the Kubernetes worker pod:

kubectl exec -it deployment/authentik-worker -c worker -- ak test_email [...]

Google Workspace SMTP relay configuration

One reliable way to send email through Google is Google's SMTP relay service. Google also documents the broader setup flow in Send email from a printer, scanner, or app.

First, determine the outbound IP address used by authentik to send emails and add it to the Google Workspace SMTP relay service settings. Then configure the relay with these options:

  • Set Allowed Senders to Only addresses in my domains.
  • Set Authentication to Only accept mail from the specified IP addresses.
  • Do not set Require SMTP Authentication.
  • Select Require TLS encryption.

<Tabs groupId="deployment" defaultValue="docker" values={[ { label: "Docker", value: "docker" }, { label: "Kubernetes", value: "kubernetes" }, ]}

If you are using Docker Compose, set the following environment variables for authentik:

AUTHENTIK_EMAIL__HOST=smtp-relay.gmail.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USE_SSL=false
AUTHENTIK_EMAIL__TIMEOUT=30

Redeploy the authentik containers, then use the ak test_email command to confirm that email delivery works.

If you are using the Kubernetes Helm chart, set the following variables in the email section of your authentik configuration file:

email:
    host: "smtp-relay.gmail.com"
    port: 587
    use_tls: true
    use_ssl: false
    timeout: 30

Redeploy the authentik containers, then use the ak test_email command to confirm that email delivery works.

SMTP server with TLS verification

If you are configuring authentik to send email via an SMTP server with TLS enabled, mount the certificate used for authentication in your authentik server and worker containers (for example a private CA bundle) and point SSL_CERT_FILE at it.

<Tabs groupId="deployment" defaultValue="docker" values={[ { label: "Docker", value: "docker" }, { label: "Kubernetes", value: "kubernetes" }, ]}

  1. Add the following configuration to the server and worker services in your Docker Compose file:
volumes:
    - /path/to/<cert_name>.crt:/etc/ssl/certs/<cert_name>.crt:ro
environment:
    - SSL_CERT_FILE="/etc/ssl/certs/<cert_name>.crt"
  1. Redeploy the containers for the changes to take effect.

  1. Create a ConfigMap with your certificate by running the following command on the Kubernetes host:
kubectl create configmap my-custom-cert --from-file=<cert_name>.crt -n <your_namespace>
  1. Create a volume by adding the following configuration to your Kubernetes values.yaml file:
volumes:
    - name: custom-ca
      configMap: # or use secret if preferred
          name: my-custom-cert
  1. Add a volumeMount and environment variable to your server and worker containers by adding the following configuration to your Kubernetes values.yaml file in the appropriate locations:
volumeMounts:
    - name: custom-ca
      mountPath: /etc/ssl/certs/ca-certificates.crt
      subPath: ca-certificates.crt
      readOnly: true
env:
    - name: SSL_CERT_FILE
      value: /etc/ssl/certs/ca-certificates.crt
  1. Recreate the pods for the changes to take effect.