E-Mail retention policies in Gmail

One of the features I miss most with my personal mail accounts is the ability to use some kind of retention policies applied to bulk messages.

While originally a compliance feature in Microsoft Exchange or the Enterprise Plans of Google Workspace, retention policies are also very useful in automatically decluttering your mailbox after a set time:

• To delete messages with order receipts after a number of years;
• To automatically delete newsletters after a few weeks or months; or
• To automatically move read messages to your archives after a few days or weeks

Unfortunately, no such feature is available in the former free G Suite tier or Gmail, and no add-in has been published in the Marketplace that would allow one to achieve this in Google’s free products.

Google Scripts to the rescue#

Luckily, with the Google Script environment, one can rather easily build such a functionality and integrate it into Gmail.

After the n-th time being frustrated with the lack of this feature, and inspired by Gmail Automation: 5 Useful Google Scripts to Automate Your Gmail, I wrote some code that

• lets you define any number of policies that either delete or archive a message threads after a number of days have passed since the last message sent/received in that thread; and
• lets you apply these through filters or manually to message threads

Building your E-Mail retention policy automation#

With the Gist published here, you can implement this for your Gmail / Google Mail accounts as well:

• Go to Google Scripts and create a blank project (make sure you are logged into your Google account);

• paste the code (below) (and modify the policies as needed);

/****
 * This Script will apply different e-mail policies according to a defined set of labels
 * Actions:
 *  - Delete: will delete (move) the message thread to the trash (unless starred)
 *  - Archive: will move the thread to the archive
 *
 * New policies: To add a new policy, add a new entry in the "policies" map
 *
 * When executing the action, the corresponding label will be removed. This will speed up the
 * processing of messages considerably (otherwise, the messages would be reprocessed on every run).
 * Starred messages will not be deleted.
 *
 * By setting a timed trigger, you can execute the script in regular intervals (e.g. every 30 minutes)
 * Create a filter that will apply a specific label automatically to the filtered mail and
 * your mailbox will unclutter itself automatically.
 *
 * Inspired/adapted from https://www.maketecheasier.com/google-scripts-to-automate-gmail/
 */

function applyEmailPolicy() {
  var policies = {
    // Archive Policies
    monthArchive: {
      label: "Archive After 30 Days",
      days: 30,
      action: "archive",
    },
    weekArchive: { label: "Archive After 1 Week", days: 7, action: "archive" },
    biWeeklyArchive: {
      label: "Archive After 2 Weeks",
      days: 14,
      action: "archive",
    },

    // Delete Policiess
    monthDelete: { label: "Delete After 30 Days", days: 30, action: "delete" },
    yearDelete: { label: "Delete After 1 Year", days: 365, action: "delete" },
    decadeDelete: {
      label: "Delete After 10 Years",
      days: 3650,
      action: "delete",
    },
  };

  for (var policyKey in policies) {
    var policy = policies[policyKey];
    Logger.log("Applying E-Mail Policy '" + policy["label"] + "'");
    var label = GmailApp.getUserLabelByName(policy["label"]);

    if (label == null) {
      GmailApp.createLabel(policy["label"]);
    } else {
      var delayDays = policy["days"];
      var maxDate = new Date();
      maxDate.setDate(maxDate.getDate() - delayDays);

      var threads = label.getThreads();
      for (var i = 0; i < threads.length; i++) {
        if (threads[i].getLastMessageDate() < maxDate) {
          switch (policy["action"]) {
            case "delete":
              if (!threads[i].hasStarredMessages()) {
                Logger.log(
                  "Deleting Thread '" +
                    threads[i].getFirstMessageSubject() +
                    "'"
                );
                threads[i].removeLabel(label);
                threads[i].moveToTrash();
              } else {
                Logger.log(
                  "Skipping Thread '" +
                    threads[i].getFirstMessageSubject() +
                    "'"
                );
              }
              break;
            case "archive":
              Logger.log(
                "Archiving Thread '" + threads[i].getFirstMessageSubject() + "'"
              );
              threads[i].removeLabel(label);
              threads[i].moveToArchive();
              break;
          }
        }
      }
    }
  }
}

• run the script manually and Gmail will
  • ask you for the permissions needed to work properly (it grants your script read/write access to your mailbox which is needed to move / delete the messages); and
  • will create the labels for each policy you defined (which is needed if you want to apply them to messages afterwards)
• set a trigger (Resources -> Current Project’s Triggers -> Add one now) to run it at the preferred interval; and
• create filters in Gmail/Google Mail that set policies when specific messages arrive

Once you’ve labeled a number of messages, you can manually run the script again and check the logs to see if the messages are found and moved to the trash or the archive.

Caveats#

• Please note that threads with starred messages will not be deleted by this script – starring them is an easy way to ensure important messages are not deleted accidentially;
• If you label messages / threads older than thirty days with a delete policy, they will immediately be deleted upon execution of the script – there’s no way to retrieve them afterwards, so be careful when applying a delete policy in bulk!;
• The archive policy will move them from the inbox to the Archive;

Credits#

Inspired and adapted from Gmail Automation: 5 Useful Google Scripts to Automate Your Gmail