Merge branch '41532-email-reason' into 'master'

Show why a notification email was sent

Closes #41532 and #1366

See merge request gitlab-org/gitlab-ce!16160

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md
index 0203757e0e1..37265a5b771 100644
--- a/doc/workflow/notifications.md
+++ b/doc/workflow/notifications.md
@@ -104,3 +104,33 @@ You won't receive notifications for Issues, Merge Requests or Milestones
 created by yourself. You will only receive automatic notifications when
 somebody else comments or adds changes to the ones that you've created or
 mentions you.
+
+### Email Headers
+
+Notification emails include headers that provide extra content about the notification received:
+
+| Header                      | Description                                                             |
+|-----------------------------|-------------------------------------------------------------------------|
+| X-GitLab-Project            | The name of the project the notification belongs to                     |
+| X-GitLab-Project-Id         | The ID of the project                                                   |
+| X-GitLab-Project-Path       | The path of the project                                                 |
+| X-GitLab-(Resource)-ID      | The ID of the resource the notification is for, where resource is `Issue`, `MergeRequest`, `Commit`, etc|
+| X-GitLab-Discussion-ID      | Only in comment emails, the ID of the discussion the comment is from    |
+| X-GitLab-Pipeline-Id        | Only in pipeline emails, the ID of the pipeline the notification is for |
+| X-GitLab-Reply-Key          | A unique token to support reply by email                                |
+| X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc             |
+
+#### X-GitLab-NotificationReason
+This header holds the reason for the notification to have been sent out, 
+where reason can be `mentioned`, `assigned`, `own_activity`, etc.
+Only one reason is sent out according to its priority:
+- `own_activity`
+- `assigned`
+- `mentioned`
+
+The reason in this header will also be shown in the footer of the notification email.  For example an email with the
+reason `assigned` will have this sentence in the footer: 
+`"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"`
+
+**Note: Only reasons listed above have been implemented so far**
+Further implementation is [being discussed here](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062)