Skip to content

Take Control of Gmail, Only Check it Once Per Hour with Google Apps Script

4 minute read

A lot of people get in the habit of checking email all day, allowing email to dictate their entire working life. A common productivity tip is to only check once an hour, or less often if you can. The theory goes that with a sufficient gap between email sessions, most ‘urgent’ problems will have solved themselves, and at the very least you won’t have interrupted your real work for every single email that came in.

I never found a perfect way to keep from checking, especially if email is also on your phone. I tried closing my Gmail browser tab, and setting a calendar reminder to check every couple of hours – but that interrupts abruptly in itself. Even with the best discipline, you often need to go back to Gmail to look something up, verify a registration to a website, or check flight information.

With no perfect solution available, I ended up using Google Apps Script to knock up a very quick solution. This script tricks Gmail into thinking that no emails have come through, then finally allowing you to see unread messages at pre-determined intervals.

This tutorial takes you through the principal steps you need to follow to build your own Gmail Freeze functionality.

Google Apps Script

Apps scripts can respond to certain events in Google Forms instantly so you can hook-in in real time, and actually change the course of action for a new form submission (for example, sending the new form data through to your own web service). Although you get a lot of deep access to Gmail functionality, it doesn’t seem possible to hook into Gmail on the same kind of level – i.e. you can’t have a script triggered whenever a new email comes in.

The closest you can get is to have a script run every minute and process new emails then. But that won’t work for us, since it’s still likely that you’ll see the Inbox (1) notification pop up in your browser, or the email will already be flashing on your phone. So, to get around that, I first have to set up Gmail so that every incoming email is hidden by default. And then every hour or so, our script can go about un-hiding them.

Setting up the Gmail Filter

It’s easy to setup a Filter in Gmail to ensure messages matching certain criteria (e.g. sent from a particular email address) are automatically ‘read’ and archived, skipping the inbox. The only problem is that you don’t seem to be able to use a filter for all incoming email. I got around that by specifying a filter that only excludes emails containing a very obscure random set of letters.

Gmail Freeze Filter

Gmail Freeze Filter (2)

As well as skipping the Inbox, you need to assign the label ‘gmail-freeze-hidden’. The idea will be for our hourly script to locate all messages with that label and bring them to Inbox, unread.

Writing the Script

Next, go to so you can type in the script. If it’s your first use, you might have to click ‘Start Scripting’ before you can create a new ‘Blank Project’. You will be given a template file and you should replace its default content with the following:

function processHidden() {
 var label = GmailApp.getUserLabelByName(“gmail-freeze-hidden”);

 if (label) {
var threads = label.getThreads();

for (var i = 0; i < threads.length; i++) {
   var thread = threads[i];
   if (thread.isUnread()) {

Save the file as ‘Gmail Freeze’ or another suitable name. You can click the run button (the right-pointing triangle on the tool bar) to run against any new emails that may have been caught by the filter already. You will need to allow Gmail to authorize the script first.

The filter as described earlier will also be applied to emails that you have sent, as well as those you have received. That’s the reason for the if (thread.isUnread()) check in the code – we don’t want your sent mail to appear in your inbox an hour after you sent it… However, the code is written to deal with conversation threads (obtained through the getThreads function), not individual messages. You do want the thread to appear in your inbox if you sent an email and somebody replied to it within the hour. That should work as expected in the filter and code shown here.

Running every hour

The only thing left to do is to tell Google to run this script every hour.

Gmail Freeze Script

From the Resources menu, select Current Project’s Triggers.

In the box, it will say No triggers set up. Click here to add one now. Click this link and you will be able to build your trigger. The default settings are the ones you are most likely to need – a time-driven trigger to run the script’s only function (‘processHidden’) every hour.

You can also tell it to send daily emails if there have been any errors running the script. To do this simply click on notifications in the same box.

Cheating and more ideas

If you want to cheat and check your email before it’s due, then you can always look at the All Mail box in Gmail, and you should see new emails as ‘read’ and labelled with our special label, waiting to be served into the inbox whenever the script is next run.

I haven’t studied how flexible the time-driven triggers can be, but if you wanted to make it flexible (e.g. to disable email completely during the night) then you could always build a check into the Javascript function itself, stopping it processing new emails depending on the time. Or if you only want emails to come through three times during the working day, maybe you can just set up three separate triggers.

Also, if your ‘gmail-freeze-hidden’ label shows up on the left in Gmail, you can set it to hide so that it doesn’t tip you off…

Sign up for our newsletter