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

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATION_URL: smtp://user:secret@smtp.example.com:587/?fromaddress=sender@example.com&toaddresses=recipient@example.com
    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:secret@smtp.example.com:587/?fromaddress=sender@example.com&toaddresses=recipient@example.com" \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notification-url "smtp://user:secret@smtp.example.com:587/?fromaddress=sender@example.com&toaddresses=recipient@example.com"

/// details | The following legacy SMTP configuration examples are deprecated and will be removed with the release of Watchtower v2. type: warning

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATIONS: email
    WATCHTOWER_NOTIFICATION_EMAIL_FROM: sender@example.com
    WATCHTOWER_NOTIFICATION_EMAIL_TO: recipient@example.com
    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: sender@example.com
    WATCHTOWER_NOTIFICATION_EMAIL_TO: recipient@example.com
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER: relay.example.com
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

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

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=sender@example.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=recipient@example.com \
-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 sender@example.com \
--notification-email-to recipient@example.com \
--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=sender@example.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=recipient@example.com \
-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 sender@example.com \
--notification-email-to recipient@example.com \
--notification-email-server relay.example.com

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

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

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	`465`
Encryption	`ImplicitTLS`
UseStartTLS	`No`

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

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.

Last updated on October 2, 2026

Migration Tool Gotify Notifications