How to create a Gmail filter based on any message headers?

Gmail has a nice feature that allows you to create filters. Filters can be used to organize your mailboxes. if you have not used this feature yet, check it out here: https://support.google.com/mail/answer/6579?hl=en. The screenshot below shows the criterias that can be used to filter messages.

As you can see from the screenshot, the feature is very limited. You can only filter message using the following criterias: From, To, Subject, Email content, size, attachment. This works for the majority of the use cases. For people that have a need to filter based on any random email headers, this is not enough. The problem we are trying to solve is this: How to filter message based on any random message header?

Every single Internet e-mail message is made up of two parts: the header and the message body of the email. Every single email you send or receive on the Internet contains a full and valid e-mail header that provides a detailed log of the network path taken by the message between the mail sender and the mail receiver(s). You can refer to this article on how to view email headers: https://it.umn.edu/services-technologies/how-tos/gmail-view-email-headers

Besides the standard headers, any application who sends email can also include other application specific email headers. The purpose of such headers is to help downstream devices (e.g., firewall, anti-virus program, etc) to take specific action for this specific header.

With the above knowledge, let’s dive into the problem we are trying to address in this article: How to filter message using any random email headers? In the example below, I want to create a label “LABELTEST” for any emails that contain a header X-LABLETEST. You need to make sure that the label in the script has to match the label you created in Gmail.

Step 1: Create a label manually

https://support.google.com/mail/answer/118708?hl=en&co=GENIE.Platform%3DDesktop

This label must be created first so that the script below can use it.

Step 2: Create a script to process each message

Go to https://script.google.com/ to create a new project. Give the project a name. Copy the sample code below into the code editor, make the necessary modification, then save the project. If you want to move the message out of the Inbox into the Spam folder, uncomment out this line:

// threads[i].moveToSpam();

function myFunction() {
   var threads = GmailApp.search("newer_than:1d");
   for (var i = 0; i < threads.length; i++) {
      var messages = threads[i].getMessages();
      for (var j = 0; j < messages.length; j++) {
         var message = messages[j];
         var body = message.getRawContent();
         if (body.indexOf("X-LABLETEST") > -1) {
            var label = GmailApp.getUserLabelByName("LABELTEST");
            threads[i].addLabel(label);
            // If you want to move the message to a spam folder,
            // uncomment out the line below
           // threads[i].moveToSpam();
         }
      }
   }
}

Step 3: Create a schedule

To create a schedule, click on the clock icon on the left panel. You will see the screenshot below. The script will runs once per minute to check for any message received in the last 1 hour.

Step 4: Authorize access to the script you just created.

You can review the source code above. The only job it is doing is to scan the message, and add label for the message. You are the author of the script. It is perfectly OK to give access to the script you just created. If you want to remove the access later, you can just delete the script. or you can remove it from your Gmail data privacy setting screen.

Your use case may be different from mine. The idea is the same. You use the script to automate your daily tasks. For more info on how to make our Gmail life easier, refer to the Gmail APIs here: https://developers.google.com/apps-script/reference/gmail.

Make the world a beautiful place by automating tasks. Comment it here if you find it useful for you.