Email Overload!

Thursday, May 31, 2012 | 1:11 PM

Labels: ,

Editor’s Note: This blog post is authored by Blair Kutzman, who developed the Gmail Delay Send script. - Eric Koleda

Update: To start using this script simply open this page and follow the instructions.

In today’s connected world, when you get your email could be just as important what’s in it. In 2011 over 107 trillion emails were sent to 1.97 billion internet users. Studies have shown that the average person can only effectively process 50 emails in a day. That leaves 100 emails per person per day that are not processed effectively. How can you be sure that the emails you send fall into the former category and not the latter?

Luckily, there are tools to assist with email overload. One such tool is Gmail Delay Send.

What is Gmail Delay Send?

Gmail Delay Send is a Google Apps Script that allows you to schedule emails to be delivered on a specified date and time. Using this tool you can ensure your email is sent to its destination at a time when you can capture your recipient’s full attention. For example, receiving an email at 4:59 PM on friday might not receive the same attention as an email received on Monday at 10:00 AM.

Designing Gmail Delay Send

A primary requirement of Gmail Delay Send was that it needed to work everywhere Gmail is available. There are already many browser add-ons and services available to enhance Gmail with similar functionality, so the purpose was not to duplicate that work. In order for the service to be available on all platforms, it needed to utilize native Gmail features.

We needed a native way that Gmail could:

  1. Store a composed, but unsent message.
  2. Store in that composed message two pieces of metadata:
    • Whether or not the message meant to be sent at a later time
    • If it is, when the message should be sent

Gmail already contains a 'Draft' folder which is exactly what is required for item 1. The real problem was where and how to store the metadata for item 2, without any new Gmail functions. I chose to encode the metadata in the subject of the message because it would contain less text, which would mean a smaller chance of mis-parsing. Text such as “5 hours” and “next tuesday” were turned into a date-time using an open source library called datejs and a few modifications. See below for details of how this potentially cumbersome process was improved.

Basic structure

The script works as follows:

  1. The user composes an email, noting the date-time they want the message to be sent in their subject line after a delimiter (eg. "Lets go surfing -- 3:30PM")
  2. The email is then saved as a draft and optionally a label is applied marking it as a message that we want to send at a later time.
  3. When the script executes, all draft messages are checked (optionally looking at messages that have a specific label applied) to see if they should be sent now.

Usability improvements

Although using datejs to parse the dates from the subject line was easy to implement, it introduced some usability issues. First, how would a user know if a certain string can be parsed by datejs (eg. is “5 minutes before 4PM” parsable)? To assist the user in knowing which dates datejs supports, the script offers a mechanism to test a given string directly in the spreadsheet that Gmail Delay Send is installed inside of. In this way a user can test various strings to see if they are valid and, if so, when they would be sent. A wiki page is dedicated to helping people through this process.

Another possibly confusing part of using Gmail Delay Send was setting up triggers. Thanks to some recent improvements of the Script Services, this is now done automatically for users as they install.

Improving script reliability

Adding retry logic to the script was another important step in improving its reliability and user experience. Occasionally, users were getting emails from their trigger informing them that a certain Google Script API could not be contacted. Some retry logic was required to make things work correctly. As shown in the snippet below, the function executeCommand() takes any function and will try to execute it a specified number of times, retrying if an error is thrown:

function executeCommand(fp) {  
  var msg;
  var ret_val;
  var last_error;

  for(var retries = NUM_RETRIES; retries > 0; retries -= 1) {
    try {
      ret_val = fp();
    catch(err) {
      last_error = err;
      msg = "Exception:" + err + " thrown executing function:" + fp;

  if(retries == 0) {
    msg = "Attempted to execute command:" + fp + " " + NUM_RETRIES +
          " times without success. Error message: " + last_error + 
          ". Aborting  :-(";
  return ret_val;

Using this method, statements like those below will automatically retry if the service is not available.

executeCommand( function() { GmailApp.send( … ) });
executeCommand( function() { UrlFetchApp.urlFetch(url) } );


Gmail Delay Send was a fantastic project for learning about Google Apps Script and I hope that it will continue to prove useful to its users. If you’re interested in using Gmail Delay Send or just interested in the development process please check out the homepage or source.

Blair Kutzman   profile

Blair currently works on scan firmware at Hewlett Packard. When not scanning he likes to hang out with family, run and surf. Check out his profile for other projects.

2 comments: said...

Marvelous! post? Insane.

Jason said...

This sounds like a brilliant concept Blair, and thank you very much for creating this function in gmail. I was looking at boomerang the other day and the only feature of their chrome extension I needed was this, so it seems pointless to spend $15 per month for their service. I did just want to confirm with you that it works in Google Apps, is that correct? If so, I will attempt to install it, even though I am not a techie, but it seems easy enough!

Thanks again!
Jason Coles
Immigration Business Plan