Problem Statement

As an SRE team, I need to monitor an email inbox and automatically create alerts when emails matching specific criteria are received. Many third-party monitoring systems, legacy applications, and external services send critical notifications exclusively via email. Without
automated email monitoring, teams must:

• Manually check shared email inboxes
• Miss time-sensitive alerts buried in email
• Build custom integrations for each email-based notification source
• Risk alert fatigue from irrelevant emails mixed with critical notifications

This creates operational overhead, increases alert response times, and introduces gaps in incident coverage.

Solution

Service-level IMAP email monitoring with OAuth 2.0 authentication, pattern-based filtering, and automated alert creation. Each service in GoAlert can now monitor its own Gmail inbox with customizable filter rules to create alerts only for relevant emails.

Key Features

Service-Level IMAP Configuration

• Per-Service Setup: Each service can monitor a different Gmail account with independent configuration
• OAuth 2.0 Integration: Secure authentication flow via Google OAuth with browser-based authorization
• Flexible Connection Settings: Configure IMAP host, port, mailbox folder, TLS settings
• Configurable Polling: Set poll intervals from 1-1440 minutes per service
• Email Handling Options: Mark emails as read and/or delete after processing

Filter Rules

• Pattern Matching: Filter emails by From, Subject, and To fields
• Match Modes: Support exact match, contains, or regex patterns
• Reply Filtering: Optionally exclude reply/forward emails (Re:, Fw:, Fwd: subjects and In-Reply-To headers)
• Multiple Rules: Create multiple filter rules per service with AND logic within each rule
• Enable/Disable: Toggle individual filter rules without deletion

Alert Creation

• Automated Alerts: Automatically create alerts in GoAlert when matching emails arrive
• Clean Content: Extract plain text email body without MIME headers or technical metadata
• Configurable Fields: Choose which email fields to include in alert details (From, To, Subject, Body, Headers)
• Service Integration: Alerts created directly on the configured service

User Interface

• OAuth Flow: Browser-based OAuth authorization with popup window
• IMAP Configuration Dialog: Easy setup of connection settings and OAuth credentials
• Filter Rule Management: Create, edit, delete, and list filter rules
• Connection Testing: Test IMAP connection before saving configuration
• Real-time Status: View configuration status and filter rules from service details page

Use Cases

1. Third-Party Monitoring Integration: Monitor alerts from external monitoring systems that only send email notifications (legacy APM tools, hardware monitoring, SaaS services)
2. Critical Business Process Notifications: Alert on-call teams when specific business process emails arrive (payment failures, data pipeline errors, compliance notifications)
3. Legacy System Monitoring: Integrate alerts from legacy applications that can't be easily modified to use modern APIs
4. Multi-Account Monitoring: Different teams monitor different Gmail accounts for their respective services without sharing credentials
5. Selective Alerting: Filter out noise by creating alerts only for emails matching specific patterns (error severity levels, specific senders, subject keywords)

Technical Implementation

Backend

• River job queue for periodic IMAP polling
• OAuth 2.0 token refresh using service-level credentials
• go-imap library for IMAP protocol
• Pattern matching with regex support
• Multipart email body extraction with plain text preference
• Service-level configuration in PostgreSQL

Frontend

• React/TypeScript with Material-UI
• GraphQL with URQL for data fetching
• FormDialog components for configuration
• OAuth popup flow with postMessage communication
• Integration with existing service details page

Security

• OAuth 2.0 for secure Gmail authentication
• Refresh tokens stored securely per service
• TLS 1.2+ required for IMAP connections
• Password fields for sensitive credentials

Migration Path

The feature includes database migrations to add:

• service_imap_config table for per-service IMAP settings
• Support for OAuth client ID, client secret, and refresh token per service
• Configuration for polling intervals, email handling, and alert content

Existing GoAlert installations can upgrade seamlessly with migrations applied automatically.

Benefits

• Reduced Operational Overhead: Eliminate manual email monitoring
• Faster Response Times: Alerts trigger on-call rotations immediately when critical emails arrive
• Flexible Integration: Connect any email-based notification source without custom development
• Noise Reduction: Filter rules ensure only relevant emails create alerts
• Secure Authentication: OAuth 2.0 avoids storing passwords or using less secure app passwords
• Team Independence: Each service team manages their own email monitoring without central coordination

This feature enables GoAlert to serve as a central alerting hub for teams that rely on email-based notifications from third-party systems, legacy applications, and external services that cannot be easily integrated through modern APIs.

This message was written with help from Claude (Claude Sonnet 4.5 noreply@anthropic.com)