Legacy Notification Configuration Option Deprecation

[nicholas-fedor]

Watchtower has supported sending notifications for a long time. This was initially implemented directly within Watchtower; however, eventually split off into a separate project, Shoutrrr. As part of that transition, service-specific configuration options and functionality were reclassified as legacy options. This has led to a number of issues, such as creating long-standing parallel paths for configuring notifications and opening the door for behavioral inconsistencies when using multiple notification services.

Under the hood, Watchtower currently parses legacy configuration options to create URLs for Shoutrrr. This was ultimately meant to be a temporary shim; however, has become a longtime fixture that has diverted Watchtower's users from properly making use of Shoutrrr URLs and the evolving functionality that it provides in its parameter-based approach. Likewise, the presence of this shim limits the addition of further improvements to Watchtower's notifications, such as dynamic notification routing and templates.

As part of the eventual release of the next major release (v2) of Watchtower, deprecation notices and warnings have been implemented to help guide users towards transitioning to using Shoutrrr URLs. I have also begun to make efforts to provide ample documentation, such as through the Watchtower website. Likewise, I have created a (rough, but functional) interactive tool available through the Shoutrrr website, which serves as an alternative to manually downloading and running the Shoutrrr binary or Docker image to to generate URLs.

I highly encourage users of the legacy configuration options to migrate to the use the notification_url configuration option. Additionally, this supports the use of Docker secrets and configuring multiple notification services via a single file (one URL per line).

Given how the legacy configuration options have long been grandfathered into Watchtower, I am attempting to provide ample warning and time for configurations to be updated. Additionally, I welcome any contributions towards improving documentation, such as the Watchtower or Shoutrrr websites, including the Shoutrrr Playground.

[seirdotexe]

For anyone using app passwords in Gmail make sure you remove the spaces 👍

[reibuehl]

I have tried to convert to the new style of email notification configuration but since I converted with docker compose exec watchtower /watchtower notify-upgrade, I don't receive email notifications anymore. What could cause this? Or do I need a new container (shoutrrr ?) to have a basic functionality like email notification now? That would be an additional dependency, so i hope not.

[reibuehl]

I did retrieve the output as described from the container and then added it to my existing docker compose file and commented out the old config:

watchtower:
    image: nickfedor/watchtower
    container_name: watchtower
    command: --cleanup --label-enable
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_NOTIFICATIONS_HOSTNAME=<dockerhost>
      - WATCHTOWER_NOTIFICATIONS=email
      - WATCHTOWER_NOTIFICATION_URL=smtp://<mailserver>:25/?auth=None&clienthost=localhost&encryption=None&fromaddress=watchtower%40<dockerhost>&fromname=Watchtower&subject=&toaddresses=<recipient>%40<recipientdomain>&usehtml=No&usestarttls=No&timeout=10s
      # - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@<dockerhost>
      # - WATCHTOWER_NOTIFICATION_EMAIL_TO=<recipient>@<recipientdomain>
      # - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=<mailserver>
      # - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY=true
      - WATCHTOWER_MONITOR_ONLY=false
      - WATCHTOWER_SCHEDULE=0 0 4 * * *
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "com.centurylinklabs.watchtower.monitor-only=false"

[janitor-of-code]

You're still telling it to use the legacy email by setting WATCHTOWER_NOTIFICATIONS=email
nowadays everything is shoutrrr so that line should propably be removed

[janitor-of-code]

I've tried to use your config and after

• turning the URL-encoded @ back to their real selfs
• setting (or removing) &subject=
• removing &clienthost=localhost

got it to working on my end

I assume subject wasn't the issue but all the others seem to be

[reibuehl]

I just tried your first suggestion of removing the WATCHTOWER_NOTIFICATIONS=email and it seems that this alone was enough to get email again. At least the email with "Using notifications: smtp" and the next scheduled run information came. The rest of the options seemed to have been no issue here - the subject of the email is correctly set to "Watchtower updates on " as before.

[nicholas-fedor]

Thanks @janitor-of-code

Yes, using WATCHTOWER_NOTIFICATIONS=email without any corresponding legacy email configuration options results in an initialization failure for Watchtower's notifications process (an empty Shoutrrr SMTP URL is an invalid configuration).

[benvia]

I tried changing the subject of the email notification using ‘&subject=’, but it didn’t work. Does anyone have a solution that works?

[janitor-of-code]

could you add a little more info?
what are your variables?
I'd guess you've set WATCHTOWER_NOTIFICATIONS=email and are still using the old setup but without seeing your config there's not much I can say

[benvia]

Notification by email is working only the subject variable is not used as the subject of the email.

[janitor-of-code]

WATCHTOWER_NOTIFICATION_SKIP_TITLE: True should do the trick as per some tests and the docs

[Its-egner]

Hi,

I also have Problems with e-mail notifications. I tried several version uf url, I got following error:

time=2026-08-23T07:48:12+02:00 level=warn msg="Notification send completed with failures" auth_failures=0 failed_count=1 network_failures=0 notify=no rate_limit_failures=0 success_count=0 total_urls=1
^C

smtp://smtp://user:pass@mail.its-egner.de:587/?auth=Plain&fromaddress=status@its-egner.de&toaddresses=admin@its-egner.de&fromname=Watchtower&usehtml=No&usestarttls=Yes&timeout=10s

Is there a Telegram Option, that would be nice.

Greetings

[nicholas-fedor]

You have smtp://smtp:// in the Shoutrrr URL. It should be smtp://.

Yes, Shoutrrr supports Telegram: https://shoutrrr.nickfedor.com/latest/services/chat/telegram/

[Its-egner]

Thank you. Telegram is working fine.

Greetings