Automatically Labeling Emails in Gmail using Google Apps Script

How to set up advanced filtering in Gmail

Photo by natsuki on Unsplash

Introduction

I recently received an email in my inbox that I immediately recognized as a phishing email. In fact, it was sent to me to test my ability to recognize phishing emails by the company I work at. Now, I’ve been tested on my ability to recognize phishing emails at all of the companies I’ve worked at over the last 5 or so years. These tests are meant to keep employees security-aware and to that point, it’s working. I remember the first time I was introduced to security awareness training. I failed miserably. That was 5 years ago and I have to say that the security awareness training has paid off as I can easily recognize a phishing attempt almost immediately. The latest attempt to test me made me curious as to whether I could automatically identify these phishing emails. I ended up creating a custom script in Google Apps Script that would automatically add a label to these fake phishing emails.

Disclaimer: This article is meant to show how to automate adding labels to emails in Gmail using Google App Scripts. I chose this fake phishing email as an example and I do not recommend avoiding this type of security awareness training.

Email Headers

The first step that I took was trying to identify if there were any indications by the email that I received on whether it was in fact a phishing test. The fake phishing email on its face didn’t give me any clues as to whether it was a fake phishing email.

Fake Phishing Email

However, when I visited the right menu in the email and I selected “Show Original”, I was able to get a lot more details about the email.

This now showed me the email headers which gave me a lot of stuff I didn’t really care about, but it did give me some key details that easily identified that the email was a test.

Delivered-To: *******
Received: *******
X-Google-Smtp-Source: *******
X-Received: *******
ARC-Seal: *******
ARC-Message-Signature: ******
ARC-Authentication-Results: *******
Return-Path: <security@microsoft-essentials-security.com>
Received: from ******.knowbe4.com (******.knowbe4.com. [**.**.**.**])
Received-SPF: ******
Authentication-Results: ******
Message-ID: <******@******.knowbe4.com>
Date: ******
From: Office 365 <security@microsoft-essentials-security.com>
Reply-To: Office 365 <security@microsoft-essentials-security.com>
To: ******
Subject: ******
Content-Type: ******
Content-Transfer-Encoding: ******
X-PHISH-CRID: ******
X-PHISHTEST: This is a phishing security test from KnowBe4 that has been authorized by the recipient organization

Aha! Yes, I had found something buried in the email headers that told me that it was a test. Now, I just needed to be able to create something that could automatically find the “X-PHISHTEST” header in all the emails in my inbox regularly.

(KnowBe4.com is a website that provides security awareness training to companies and organizations)

Google Apps Script

In order to automatically find the “X-PHISHTEST” header in the emails in my Gmail account, I first tried to create some kind of rule in Gmail that would automatically find the email but the options to create a rule were very limited. I ended up turning to Google Apps Script. Here I would be able to create a project that could run a function against the emails in my inbox. I could then create a trigger that would run the function every 1 minute automatically.

Selecting the option to create a new project will open up a new window with a new “untitled project”. I updated the name of the project to be “Gmail KnowBe4 Script”. I replaced the code that is in the “Code.gs” text area with the following text and then saved the script.

function myFunction() {
   var threads = GmailApp.search("newer_than:1h");
   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-PHISHTEST") > -1) {
          var label = GmailApp.getUserLabelByName("Phishing Test");
          threads[i].addLabel(label);
        }
      }
   }
}

For this to work correctly, I needed to create a new label in my Gmail account that has the name: Phishing Test

I could have used any name for the label. If I had used a different name then I would’ve just needed to update the script to use the label name replacing where it says “Phishing Test” as shown in the example below. Don’t forget to save the script!

var label = GmailApp.getUserLabelByName("New Label Name");

Script Trigger

Now that I had the script created and a matching label in Gmail, I needed to create a trigger that will automatically run the script every 1 minute. I clicked the trigger icon to start creating a trigger for the script.

Google Apps Script Trigger Icon

I then clicked the button to “Add Trigger”. I updated the add trigger form to run every 1 minute and then saved the trigger.

Add Trigger Form

When saving the trigger, I was prompted to choose a Google account in order to continue authorizing my new script to run. I continued with any prompts that asked me to allow access to my Google account with the script I created.

After the trigger was saved and I had authorized the script to run within my Google account, all future fake phishing emails now automatically have a label added to them when they arrive in my Gmail inbox.

Phishing Test Label Attached to Email

Conclusion

Google Apps Scripts is very powerful within the Google ecosystem and has a ton of use cases. This was one specific use case where Google Apps Script helped me create an automated solution to an advanced filtering problem in Gmail. I hope this article will inspire someone to find other opportunities to use Google Apps Script.