How to Use Google Apps Script to Automate Gmail Filters

Gmail’s built-in filters are powerful, allowing you to automatically apply labels, archive, or delete incoming emails based on specific criteria. However, native Gmail filters have severe limitations: they cannot execute complex logic, they cannot modify emails after they have arrived, and they cannot interact with external services.

If you need advanced email automation—such as automatically purging emails older than 30 days from a specific label, forwarding emails conditionally based on the day of the week, or extracting data from attachments—you need Google Apps Script.

What is Google Apps Script?

Google Apps Script is a cloud-based JavaScript platform that allows you to automate tasks across Google products, including Gmail, Google Sheets, and Google Drive. Because it runs directly on Google’s servers, your scripts will execute automatically in the background even when your computer is turned off.

How to Create Your First Gmail Automation Script

In this example, we will create a script that automatically deletes emails in a specific label (“Newsletters”) that are older than 14 days. This is a highly requested feature that native Gmail filters simply cannot perform.

1. Go to script.google.com and sign in with your Google account.
2. Click the New project button in the top left corner.
3. In the editor, delete the default code (function myFunction() { }) and paste the following script:

function cleanUpNewsletters() {
  // Define the label and the maximum age in days
  var labelName = 'Newsletters';
  var maxDays = 14;
  
  // Calculate the date threshold
  var maxDate = new Date();
  maxDate.setDate(maxDate.getDate() - maxDays);
  var searchQuery = 'label:' + labelName + ' before:' + maxDate.getFullYear() + '/' + (maxDate.getMonth() + 1) + '/' + maxDate.getDate();
  
  // Fetch the email threads matching the query
  var threads = GmailApp.search(searchQuery);
  
  // Move matching threads to the trash
  for (var i = 0; i < threads.length; i++) {
    threads[i].moveToTrash();
  }
}

4. Click the floppy disk icon in the toolbar to save the project, and give it a name like “Gmail Auto-Cleanup”.
5. Click the Run button in the toolbar. Google will ask for permission to access your Gmail account. Click Review permissions, choose your account, click Advanced, and select Go to Gmail Auto-Cleanup (unsafe) to authorize the script.

How to Automate the Script Using Time-Driven Triggers

Your script currently works, but it only runs when you manually click the Run button. To make this an actual automated filter, you need to set up a Time-Driven Trigger.

1. In the Apps Script editor, click the Triggers icon (it looks like a clock or an alarm) on the left sidebar.
2. Click the Add Trigger button in the bottom right corner.
3. Configure the trigger with the following settings:
   • Choose which function to run: cleanUpNewsletters
   • Select event source: Time-driven
   • Select type of time based trigger: Day timer
   • Select time of day: Midnight to 1am (or whenever you prefer)
4. Click Save.

Your custom Gmail filter is now fully automated. Google’s servers will run your JavaScript code every night between midnight and 1 AM, searching for emails labeled “Newsletters” that are older than two weeks and automatically moving them to the trash.