authentik/website/docs/install-config/email.mdx

---
title: 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](../sys-mgmt/events/notifications.md), and any [Email stage](../../add-secure-apps/flows-stages/stages/email/) 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" },
  ]}
>
  <TabItem value="docker">

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

```sh
# 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
```

  </TabItem>
  <TabItem value="kubernetes">

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

```yaml
# 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"
```

  </TabItem>
</Tabs>

### When to use stage-specific settings

[Email stages](../../add-secure-apps/flows-stages/stages/email/) 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:

```shell
ak test_email <to_address>
```

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

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

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

To run this command with Docker Compose:

```shell
docker compose exec worker ak test_email [...]
```

  </TabItem>
  <TabItem value="kubernetes">

To run the command in the Kubernetes worker pod:

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

  </TabItem>
</Tabs>

## Google Workspace SMTP relay configuration

One reliable way to send email through Google is [Google's SMTP relay service](https://support.google.com/a/answer/2956491). Google also documents the broader setup flow in [Send email from a printer, scanner, or app](https://support.google.com/a/answer/176600?hl=en).

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" },
  ]}
>
  <TabItem value="docker">
If you are using Docker Compose, set the following environment variables for authentik:

```sh
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.

  </TabItem>
  <TabItem value="kubernetes">

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

```yaml
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.

  </TabItem>
</Tabs>

## 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" },
  ]}
>
  <TabItem value="docker">

1. Add the following configuration to the server and worker services in your Docker Compose file:

```yaml
volumes:
    - /path/to/<cert_name>.crt:/etc/ssl/certs/<cert_name>.crt:ro
environment:
    - SSL_CERT_FILE="/etc/ssl/certs/<cert_name>.crt"
```

2. Redeploy the containers for the changes to take effect.

  </TabItem>
  <TabItem value="kubernetes">

1. Create a `ConfigMap` with your certificate by running the following command on the Kubernetes host:

```sh
kubectl create configmap my-custom-cert --from-file=<cert_name>.crt -n <your_namespace>
```

2. Create a volume by adding the following configuration to your Kubernetes `values.yaml` file:

```yaml
volumes:
    - name: custom-ca
      configMap: # or use secret if preferred
          name: my-custom-cert
```

3. 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:

```yaml
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
```

4. Recreate the pods for the changes to take effect.

  </TabItem>
</Tabs>