Additional headers added to email notifications for better filtering

[ebndev]

What's changed

We’re now including the labels, assignees, milestones, and issue types directly in the email headers for issue and pull request emails.

Labels and issue types are essential for organization, but until now, there wasn't a way to use them to filter notifications. As a result, many users have resorted to complex email filters to keep up with the most important conversations. This update enables better auto-filtering and searching by metadata in a supported email client and lets you set up more effective email filters based on your team, project, or workflow.

These headers will be populated based on the fields that are set in your issue or pull request, but can include the following:

• X-GitHub-Labels
• X-GitHub-Assignees
• X-GitHub-Milestone
• X-GitHub-IssueType.

If these fields are not populated in the issue or pull request, they will be empty or hidden in the email.

Examples

While most email clients support filtering by custom headers, Gmail and Apple Mail may require extra configuration. See details below:

How to filter by custom headers in Gmail

1. Open Gmail.
2. Click the Settings icon in the top toolbar and select See all settings.
   

3. Go to the Add-ons tab, then click the Apps Script link.
   

5. This opens your Apps Script dashboard. Click Create Apps Script.
   

6. Name your project. In the code editor, paste the script from here.
   

The processInbox() function finds all emails in threads received within the last day where the header X-Github-Assignees includes lindseywild. If found, the thread is marked as important and given the GH Assigned label.

8. Save your code using the toolbar and click Run to trigger the script immediately. You can view logs at the bottom of the editor.
   

9. To schedule the script, click Triggers in the left sidebar.
   

10. Click Create a new trigger. Select the function and frequency, then click Save.
    

12. Once your script runs, you should see the filter working. For example, the GH Assigned label is applied to emails where the assignee is @lindseywild (X-Github-Assignees: lindseywild).
    

How to filter by custom headers in Apple Mail

1. Open the Mail app on your Mac.
   
2. Select an email containing the custom header you want to filter by.
   
3. Go to View > Message > All Headers to view all headers.
   

4. In the image below, headers like X-Github-Issuetype, X-Github-Labels, and X-Github-Assignees appear highlighted.
   

5. To add a filter, go to Mail > Settings > Rules.
   

6. Click Add Rule, then name and describe your rule.
   

7. Under If any of the following conditions are met, select a header, condition, and value. If your header isn’t in the dropdown, click Edit Header List.
   

8. Add your custom header name and click OK.
   

9. Your custom header now appears in the dropdown. Select your header, condition, and value. This example filters emails where X-Github-Labels equals "tiny win".
   

10. Under Perform the following actions, select an action (such as moving emails to a mailbox or marking as read).
    
    For example, emails with X-Github-Labels: tiny win are moved to the "Tiny Wins" mailbox.
    

11. Click OK to add your rule. Filtering is now enabled.
    

12. (Optional) To run an AppleScript for advanced filtering, select Run AppleScript as the action and attach your script.
    

How to give feedback

We'd love to about how this change is impacting your workflow. Feel free to leave any feedback or issues you find in the discussion below!

[AdamWr]

Question maybe not exactly about new features, but perhaps it's somehow related because it started about 2 days ago.
It's about e-mail notifications and Unread notifications on https://github.com/notifications?query=is%3Aunread
I'm referring to - https://docs.github.com/en/subscriptions-and-notifications/get-started/configuring-notifications

If you receive notifications both via email and on GitHub, you can automatically sync the read or unread status of the notification so that notifications on GitHub are automatically marked as read once you've read the corresponding email notification. To enable this sync, your email client must be able to view images from notifications@github.com.

It seems that this option does not work anymore. When I receive email notification and read it, then it's not marked as read on https://github.com/notifications?query=is%3Aunread
If I'm not wrong, it looks like emails notifications are missing this special image to sync read status.
I'm not sure if I'm the only one with this problem or maybe this option has been disabled intentionally?

[moraesc]

Hey @AdamWr! We're looking into this now and will get back to you as soon as we have some updates. Thank you!

[AdamWr]

It looks like that it has been fixed.
Thank you :)

[kellyarwine]

Thanks for flagging this, @AdamWr. We’re re-evaluating the logic in emails that mark a notification as “read.” We had removed this behavior, but after hearing from folks who rely on it, we rolled it back while we do more research.

We’d are interested in better understanding your use case before making any more changes. Please email me at [deleted]. If I don’t hear from you, I’ll circle back and remove my email from this thread in 7 days.

Your input would be valuable.

[AdamWr]

I've sent you an email.

[Gaardsholt]

Is it possible to filter out all e-mails regarding a pull request created by a bot?

[moraesc]

Great question @Gaardsholt ! To my knowledge there's not a way at the moment, but if you check out this thread there's discussion around finding a way to hide notifications for comments marked as spam, so potentially the same could be done for pull requests. We'll keep in this mind and I'll share any updates if we're able to make progress in this area.

[Gaardsholt]

I don't seem to have access to that repo :(

[offbyone]

I have a fairly extensive Gmail / Google Apps Script that leverages some of these values to organize my PRs further.

The main thing it does is bucket my PRs into per-repository labels, nested under GH/repo/ which allows me to trivially see where my PRs are coming from. It runs on a schedule, because I haven't gotten it to be effective at reacting to new emails directly.

function processInbox() {
  processSearch("newer_than:1h", "GH/repo/");
}

function processSearch(search, repoLabelPrefix) {
  var threads = GmailApp.search(search);
  threads.forEach(function(thread, _, _) {
    thread.getMessages().forEach(function(message, _, _) {
      if (message.getHeader("X-Github-Reason")) {
        var repositoryUrl = message.getHeader("List-Archive");
        var repositoryName = getRepository_(repositoryUrl);

        if (! alreadyLabeled_(thread, repoLabelPrefix)) {
          console.log(`Found message: ${message.getId()}/${message.getHeader("X-Github-Reason")} with repository name ${repositoryName} from list URL ${repositoryUrl}`);

          if (repositoryName != null && repositoryName.length > 0) {
            var labelName = repoLabelPrefix + repositoryName;
            addLabel_(thread, labelName);
            thread.moveToArchive();
          }
        }
        else {
          console.log("Skipping already-labeled repository message " + message.getSubject());
        }
      }
    })
  });
}

function alreadyLabeled_(thread, prefix) {
  // split out here for debuggability
  var allLabels = thread.getLabels();
  var existingRepoLabels = allLabels.filter(function(value, _, _) {
    try {
      // split out here for debuggability
      var labelName = value.getName();
       return labelName.startsWith(prefix);
    }
    catch (Error) {
      return false;
    }
  });
  return existingRepoLabels.length > 0;
}

function addLabel_(thread, labelName) {
  console.log(`thread: ${thread}, label name: ${labelName}`)
  var existingLabel = GmailApp.getUserLabelByName(labelName);
  if (existingLabel == null) {
    existingLabel = GmailApp.createLabel(labelName);
  }
  existingLabel.addToThread(thread);
  return existingLabel;
}

function getRepository_(repositoryUrl) {
  // assume that this is a valid structure URL.
  var path = repositoryUrl.substring(repositoryUrl.indexOf("/", 8) + 1);
  return path;
}

[abmantis]

Any chance of also getting the status? It would be nice to be able to add a "Merged" label automatically!

[moraesc]

@abmantis We're looking into this and I'll keep you notified on any updates! One thing to call out is that the status header would show up on every message, so if you want to track state changes that’ll likely need more scripting work.

[moraesc]

@abmantis we just added 2 new labels:

• X-GitHub-IssueState -- if the notification is for an issue, this header will indicate the issue state
• X-GitHub-PullRequestStatus -- if the notification is for a PR, this header will indicate the PR status

Let me know if you have any questions about this!

[abmantis]

Oh that is great! I'll try it out later today.
Thank you!

[abmantis]

A bit of feedback after quickly checking it out:

• both merged and closed (without merge) PRs have X-GitHub-PullRequestStatus: closed. Is it possible to distinguish merged from closed?
• the email of a merge action (the one with the Merged #152147 into dev. text) does not have the X-GitHub-PullRequestStatus header. Usually, the one before does have it. I guess it is only sent once when state changes?
• There seems to be no state for Draft PRs.

EDIT: merged PR status is now also indicated!

[VictorMoni]

Bravo @ebndev 👏😄

[abmantis]

There was a PR where I (not the author) commented and merged it. Later, the author added a comment on the PR. The e-mail I received for that comment had the proper X-GitHub-PullRequestStatus: merged, but the wrong reason: X-GitHub-Reason: state_change. There was no state change at that point, just a comment.

[moraesc]

Hi @abmantis ! I got confirmation that merging a PR is actually considered a state_change, so the X-GitHub-Reason header value is as expected. Apologies for any confusion here. In certain cases the X-GitHub-Reason indicates the subscription reason and in other cases it indicates the activity trigger. In this case, the X-GitHub-Reason value is indicating the reason you will receive subsequent notifications. Let me know this is clear or if you have any other questions!

[abmantis]

Thanks for the clarification @moraesc .
Unfortunately that makes it harder to label it properly, since I never get an e-mail with either reason:comment or reason:participating, so it mixes with other non-priority e-mails.

[moraesc]

@abmantis yeah I understand and am sorry for the difficulty. I'll see if there's anything we can do to improve the reason header down the line.

[abmantis]

Just as an additional piece of feedback from another PR that is related:

• PR was opened and a review was requested from the team I belong to.
• I added comments on the PR.
• Author replied -> I receive an e-mail with the reason review_requested, and not comment.

This makes it impossible to label it as a PR that I've interacted with and separate them from team review requests, for example.

I think this is not specific to e-mails, but general notifications, but wanted to provide it as feedback :)

[carson-moore-sp]

Wanted to +1 the feedback above. I'm not sure how it has worked historically, but I think notification reasons should have a hierarchy. If I'm review_requested and then I leave some comments on the PR, any future activity should be comment. Alternatively, the email could contain multiple reasons.