Email Notifications¶

Deprecated Email Notification Options

The following legacy email notification options are deprecated and subject to removal with the release of Watchtower v2:

Use the notification-url configuration option with a smtp:// Shoutrrr URL instead.

Use the legacy notifications migration tool to help with migrating to a Shoutrrr URL.

Overview¶

Watchtower uses Shoutrrr's SMTP service to send email notifications.

Examples¶

Docker ComposeDocker CLI (Env Vars)Docker CLI (Flags)

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATION_URL: smtp://user:[email protected]:587/[email protected]&[email protected]
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATION_URL="smtp://user:[email protected]:587/[email protected]&[email protected]" \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notification-url "smtp://user:[email protected]:587/[email protected]&[email protected]"

The following legacy SMTP configuration examples are deprecated and will be removed with the release of Watchtower v2.

Docker ComposeDocker CLI

Docker ComposeSMTP Relay

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATIONS: email
    WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.example.com
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: user
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: secret
    WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 10
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATIONS: email
    WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER: relay.example.com
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Note

The example assumes that your domain is called example.com and that you are going to use a valid certificate for smtp.example.com.

This hostname has to be used as WATCHTOWER_NOTIFICATION_EMAIL_SERVER, otherwise the TLS connection will fail with Failed to send notification email or connection: connection refused errors.

We also have to add a network for this setup in order to add an alias to it.

If you also want to enable DKIM or other features on the SMTP server, then you will find more information at freinet/postfix-relay

Env VarsFlagsEnv Vars (SMTP Relay)Flags (SMTP Relay)

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=user \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=secret \
-e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=10 \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notifications email \
--notification-email-from [email protected] \
--notification-email-to [email protected] \
--notification-email-server smtp.example.com \
--notification-email-server-port 587 \
--notification-email-server-user user \
--notification-email-server-password secret \
--notification-email-delay 10

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=relay.example.com \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notifications email \
--notification-email-from [email protected] \
--notification-email-to [email protected] \
--notification-email-server relay.example.com

Note

This assumes that you already have an SMTP server up and running that you can connect to. If you don't or you want to bring up Watchtower with your own simple SMTP relay, then check out the Docker Compose example.

Common SMTP Configurations¶

GmailAWS SESMicrosoft 365Generic (SSL)Generic (Plain)

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://user%40gmail.com:${PASSWORD}@smtp.gmail.com:587/?fromaddress=user%40gmail.com&toaddresses=user%40gmail.com&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Note

For Gmail, use an App Password if two-factor authentication is enabled.

Omit spaces from the App Password. Google displays the 16-character passcode in groups of four, but those spaces are not part of the password.

URL-encode @ in the username as %40.

Do not use &auth=OAuth2 with an App Password. That method expects a SASL XOAUTH2 access token in the password field.

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://${USER}:${PASSWORD}@email-smtp.us-east-1.amazonaws.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://${USER}:${PASSWORD}@smtp.office365.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Property	Value
Port	`465`
Encryption	`ImplicitTLS`
UseStartTLS	`No`

smtp://${USER}:${PASSWORD}@smtp.example.com:465/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ImplicitTLS&usestarttls=no&timeout=30s

Property	Value
Port	`25`
Encryption	`None`
UseStartTLS	`No`

smtp://${USER}:${PASSWORD}@smtp.example.com:25/?fromaddress=${FROM}&toaddresses=${TO}&encryption=None&usestarttls=no&timeout=30s

Notes¶

Timeout:
- The default SMTP timeout is 10 seconds.
- If you experience timeouts (e.g., failed to send: timed out: using smtp), add &timeout=30s to the URL to allow more time for server responses, especially with proxies or slow networks.
Authentication:
- Use &auth=Plain for username and password authentication, including Gmail App Passwords. This is the default when credentials are provided.
- Use &auth=OAuth2 only for SASL XOAUTH2 with a static access token in the password field. App Passwords are not OAuth2.
Testing:
- Install Shoutrrr using one of the various installation methods.
- Test your URL with the Shoutrrr CLI:
```
shoutrrr send -u <URL> -m "Test message"
```
Proxy Issues:
- If using a Docker proxy (e.g., tcp://dockerproxy:2375), ensure it allows outbound connections to ${SMTP_HOST}:${SMTP_PORT}.
- Test connectivity with telnet ${SMTP_HOST} ${SMTP_PORT} inside the container.