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: ghcr.io/sidneyojr/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" \
ghcr.io/sidneyojr/watchtower

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

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: ghcr.io/sidneyojr/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: ghcr.io/sidneyojr/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

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=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 \
ghcr.io/sidneyojr/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/sidneyojr/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 \
ghcr.io/sidneyojr/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/sidneyojr/watchtower \
--notifications email \
--notification-email-from sender@example.com \
--notification-email-to recipient@example.com \
--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}:${PASSWORD}@smtp.gmail.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Note

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

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/password authentication (default if credentials provided).
- For OAuth2 (e.g., Gmail with app-specific passwords), use &auth=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.