Read the Docs + GitHub: getting failure-only build alerts without the success noise

The Short Answer

There is currently no native setting in the Read the Docs (RTD) dashboard or API to configure the built-in email notification system to trigger only on failed builds. The notification toggle in Settings → Notifications is binary; it either sends an email for every build outcome or sends none at all.

Analysis of Configuration Options

The Email Notification System

The internal email alerts are handled by the RTD platform's core notification engine. These are distinct from the webhooks sent to GitHub. Because these emails are generated internally, they do not respect the event-filtering logic available to external webhooks. This behavior is consistent across both the Community and Business tiers.

The API and Webhooks

While the RTD API allows for the management of webhooks, these endpoints control the data sent from RTD to an external service (like GitHub). Modifying a webhook via the API cannot "silence" the internal email system. Furthermore, the native GitHub integration creates a managed webhook that is designed to sync build statuses to the GitHub commit UI; it is not a replacement for the email alert system.

Recommended Low-Noise Pattern

To eliminate success noise while ensuring failures are never missed without introducing a complex third-party relay, the most reliable pattern is to disable RTD email notifications entirely and shift your alerting to GitHub's native commit status notifications.

1. Disable RTD Emails: Go to Settings → Notifications and toggle off build notifications. This stops the "success noise" at the source.
2. Leverage GitHub Statuses: Since the native integration is already active, RTD sends a success or failure status to every commit/PR.
3. Configure GitHub Notifications: In your GitHub account settings, ensure you are notified of failed status checks. GitHub's notification engine is designed to alert you when a check fails, whereas it typically remains silent (or provides a subtle UI indicator) when a check passes.

This approach removes the external failure point of a middleware script while utilizing the existing integration path already established between RTD and GitHub.

Verification Step

To verify this setup, introduce a deliberate syntax error in your conf.py or a .rst/.md file and push the change. Confirm that the GitHub commit status turns red and that you receive a GitHub notification, while no email is sent for subsequent successful fixes.

Missing Detail: Please specify if you are using a custom domain or a specific email relay for your project, as this may affect how GitHub notifications are routed to your team.