feat: implement phantom_threading to group email alerts into threads

Some email clients such as Gmail apparently use their own heuristics
for threading and already implement this behavior based on the subject.

But for users of other email clients that only implement threading
based on the relevant headers (e.g. notmuch), those users currently
get one email thread for each newly firing alert.

With phantom_threading enabled, all alert emails (of the same alert)
on the same day are grouped into the same thread. Much nicer :)

Signed-off-by: Michael Stapelberg <[email protected]>

Author: stapelberg

config/notifiers.go

@@ -304,6 +304,7 @@ type EmailConfig struct {
 	Text             string               `yaml:"text,omitempty" json:"text,omitempty"`
 	RequireTLS       *bool                `yaml:"require_tls,omitempty" json:"require_tls,omitempty"`
 	TLSConfig        *commoncfg.TLSConfig `yaml:"tls_config,omitempty" json:"tls_config,omitempty"`
+	PhantomThreading bool                 `yaml:"phantom_threading,omitempty" json:"phantom_threading,omitempty"`
 }
 
 // UnmarshalYAML implements the yaml.Unmarshaler interface.

docs/configuration.md

@@ -986,6 +986,10 @@ tls_config:
 # Further headers email header key/value pairs. Overrides any headers
 # previously set by the notification implementation.
 [ headers: { <string>: <tmpl_string>, ... } ]
+
+# Whether to use Phantom Threading, which results in one thread per day
+# instead of one thread per alert.
+[ phantom_threading: <boolean> | default = false ]
 ```
 
 ### `<msteams_config>`

notify/email/email.go

@@ -265,6 +265,19 @@ func (n *Email) Notify(ctx context.Context, as ...*types.Alert) (bool, error) {
 		fmt.Fprintf(buffer, "Message-Id: %s\r\n", fmt.Sprintf("<%d.%d@%s>", time.Now().UnixNano(), rand.Uint64(), n.hostname))
 	}
 
+	if n.conf.PhantomThreading && len(as) > 0 {
+		// Add threading headers. All notifications for the same alert
+		// (identified by fingerprint) on the same day are threaded together.
+		// The thread root ID is a phantom Message-ID that doesn't correspond to
+		// any actual email. Email clients following the (commonly used) JWZ
+		// algorithm will create a dummy container to group these messages.
+		threadRootID := generateThreadRootID(as, n.hostname)
+		if threadRootID != "" {
+			fmt.Fprintf(buffer, "References: %s\r\n", threadRootID)
+			fmt.Fprintf(buffer, "In-Reply-To: %s\r\n", threadRootID)
+		}
+	}
+
 	multipartBuffer := &bytes.Buffer{}
 	multipartWriter := multipart.NewWriter(multipartBuffer)
 
@@ -385,3 +398,18 @@ func (n *Email) getPassword() (string, error) {
 	}
 	return string(n.conf.AuthPassword), nil
 }
+
+func generateThreadRootID(alerts []*types.Alert, hostname string) string {
+	if len(alerts) == 0 {
+		return ""
+	}
+
+	// Use first alert as representative of the alert group.
+	alert := alerts[0]
+	fingerprint := alert.Fingerprint().String()
+
+	// Use current date so all mails for this alert today thread together.
+	date := time.Now().Format("2006-01-02")
+
+	return fmt.Sprintf("<alert-%s-%s@%s>", fingerprint, date, hostname)
+}