Upgrade and harden Apprise notifications

[ebhills]

Summary

Upgrade and pin Apprise to a tested version, then harden the Wrangles notification connector so invalid notification URLs and failed deliveries are surfaced instead of silently appearing successful.

Background

This issue originated when PRA email notifications appeared to stop working. That incident was ultimately not an Apprise regression: wrangleworks.com had been placed on registrar clientHold after the Squarespace payment method expired, removing the domain from DNS and causing recipient MX lookups to return NXDOMAIN.

The investigation nevertheless identified real weaknesses in the Wrangles notification integration that should be addressed separately.

Current behavior

• requirements.txt specifies apprise without a version constraint, so clean installs can silently resolve different Apprise releases.
• wrangles.connectors.notification.run() ignores the result of both:
  • Apprise.add(url)
  • Apprise.notify(...)
• The wrapper always returns None, even when Apprise returns False for an invalid URL or failed delivery.
• Email URLs are assembled manually. Credentials and recipient values are not comprehensively URL-encoded, so reserved characters such as & can change the parsed value.
• Errors must not expose the full notification URL because it can contain SMTP credentials.

Investigation results

Apprise 1.9.7, 1.11.0, and 1.12.0 were compared using the URLs generated by Wrangles:

• Existing mailto:// and mailtos:// URLs were accepted by all three versions.
• The add() and notify() result contracts were unchanged.
• No email URL-parser regression was found.
• Apprise 1.12.0 added certificate-verifying SSL contexts for SMTPS and STARTTLS. Invalid, self-signed, hostname-mismatched, or incomplete certificate chains may therefore fail where older versions connected insecurely.
• Focused characterization tests passed under both 1.9.7 and 1.12.0.

Apprise 1.12.0 is the current release as of this issue update, but the latest compatible release should be rechecked when implementation begins.

Proposed scope

Dependency

• Select and pin an exact, tested Apprise version.
• Test the selected version on every Python version supported by Wrangles.
• Document the intentional version change.

Notification result handling

Preserve the existing success contract where practical—successful calls may continue returning None—but fail clearly when Apprise reports failure:

• If Apprise.add(url) is not successful, do not call notify(); raise a clear configuration error.
• If notify() is not successful, raise a clear delivery error.
• Include useful, sanitized context such as notification type or title.
• Never include passwords, tokens, or the complete credential-bearing URL in logs or exception messages.

URL construction

• Properly encode SMTP usernames, passwords, sender names, and recipient parameters.
• Preserve existing support for to, cc, bcc, custom SMTP hosts, common providers, message format, and attachments.
• Do not weaken TLS certificate verification to preserve compatibility.

Tests

Add focused behavioral coverage for:

• successful add() and notify();
• rejected/invalid URLs;
• failed delivery after a URL is accepted;
• ensuring notify() is not called when add() fails;
• sanitized exceptions that do not contain credentials;
• reserved characters in credentials and recipient addresses;
• custom SMTP and common-provider URL construction;
• HTML format and attachments;
• Telegram and Slack delegation remaining unchanged.

Out of scope

• The resolved Squarespace/domain-DNS incident.
• Changing RSIS workflow behavior.
• Disabling SMTP TLS verification.
• A broader notification API redesign unless required for backward compatibility.

Acceptance criteria

• Apprise is pinned to an explicitly tested version.
• Supported Python test environments pass with that version.
• Invalid notification URLs fail visibly and do not call notify().
• Delivery failures fail visibly rather than returning apparent success.
• Successful notification calls preserve existing caller compatibility.
• SMTP credentials and recipients are safely encoded.
• Logs and exceptions never expose credential-bearing URLs or secrets.
• Email, Telegram, Slack, format, and attachment behavior have focused regression coverage.
• Release notes identify the dependency and failure-reporting behavior changes.