An example use of IMAPFilter that converts flagged Gmail messages into Gcal messages.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Gmail2Gcal is an enhanced Gmail notification system. It allows you to easily filter Gmail messages and turn the important ones into Gcal events. Gmail2Gcal leaves the filtering of emails and the notification of calendar events to already existing strategies.

While there are existing email notification mechanisms, I have found them all to be lacking. The problems I’ve encountered are:

  1. Too many notifications to be useful if I receive a notification on every inbound email.
  2. Too few and unpredictable notifications when I rely on smart filtering systems such as Gmail’s importance rankings.
  3. Computer and bandwidth resource constraints when I try to filter the full text of every email, using procmail or a similar, client-side filtering technology.
  4. Inability to create adequate filters if I force my client-side filtering to only use the email headers without access to the email body.

Even if I implement the perfect filtering system, I am left with one problem that effectively renders exist email notification useless for me: Email notifications are not persistent. Either they beep once and then they are quiet or they beep every 5 or so minutes. One notification is not enough for me and endless notifications overloads me.

What Gmail2Gcal provides is a means of connecting Gmail’s reasonably functional and free filtering functionality to Gcal. It utilizes the fact that while notifications for email are weak, notifications for calendar events include rich functionality such as snooze, nags, toast notifications, etc…

By offloading the heavy lifting to Google’s email, filtering, and calendaring services and offloading the notification functionality to my Android smartphone, Gmail2Gcal provides high functionality with low resource utilization. In fact, the resource cost is so low that I have a live demo up and running for anyone to play around with.

I should mention that Gmail2Gcal is not, nor does it try to be, a means of managing your calendar via email. There already exist many strategies that provide such functionality. Besides, personally, I don’t find that I utilize such functionality useful.

See A Live Demo

Assuming that I haven’t broken anything, there is a live demo of Gmail2Gcal that you can play around with. All I ask is that you be forgiving if you run into any problems. This is using my personal Gmail and Gcal account and my personal VPS Linux box which has a rather small bandwidth capacity.

To use the live demo, simply send an email to While the body of the message can be empty, the subject of the email will be used as the title of the calendar event. I recommend adding a subject that is more unique than test.

Shortly after you send the email you will receive a reply that will tell you how to view your newly created Gcal event.

For this demo I have disabled notifications because, being that it is my Gcal, I would be the person getting the notifications rather than you. The code in this repository includes support for notifications.

I ask that you do not use this email for spam or other inappropriate activities. If that happens I will be forced to shut down the live demo.

Installation Requirements

  • A Gmail and Gcal account.
  • This has been written and tested under Ubuntu 10.4 Linux. It should work on other operating systems but YMMV. If you are on Windows, my advice is that you to upgrade to Linux. If you can’t or just plain won’t upgrade to Linux, installing Cygwin should allow a successful installation of Gmail2Gcal. Once again, YMMV. TODO: Find out of IMAPFilter runs on Windows.
  • Either a working crontab system or another mechanism to execute IMAPFilter at regular time intervals. It should be possible, and possibly more efficient, to use IMAPFilter’s “become\_daemon” command to schedule execution of Gmail2Gcal. I did not do this as I found using a cron job easier than using “become\_daemon”. See extend.lua in IMAPFilter’s repository for an example of “become\_daemon”. Contributions in this area would be most appreciated.
  • Installation of the GoogleCL Google Command Line interface program. Installation is well documented and relatively straightforward. GoogleCL is supported on most operating systems.
  • Either a bash shell or perhaps an sh shell. Note that this has not been tested with an sh shell.
  • If you will be setting reminders with Gmail2Gcal, it is preferable to install Gmail2Gcal on a computer that is permanently connected to the internet.
  • Familiarity with Gmail labels and filters.

Installation Process

While no step is complex, there are several steps required to install Gmail2Gcal. Skipping any step will likely leave you with a non-working installation.

Installing Bash (likely only for Windows users)

  1. If you don’t bash installed, install Cygwin if you are on Windows or directly install bash from its homepage.

Install GoogleCL

  1. Follow the documentation for installing GoogleCL.

Gmail Setup

  1. Make sure you have a Gmail account.
  2. Create a new label in Gmail that you will use for emails that you want to have processed by Gmail2Gcal. I recommend the label _Gmail2Gcal though you can choose a different one. I use the leading underscore (_) to cause the label to appear near the top of Gmail’s label list.
  3. Configure filters TODO

Gcal Setup

  1. Make sure that you have a Gcal account.
  2. If you wish to use a calendar other than your default Gcal calendar for Gmail2Gcal events, create that calendar in Gcal. I use a calendar name Reminders though that is just my personal choice.
  3. If you have created a calendar in the previous step, edit the gmail2gcal shell script and follow the directions at the top of the file for specifying which calendar should be used.

Installing IMAPFilter

  1. TODO

Configuring IMAPFilter

  1. TODO

Configuring Cron

  1. TODO


  1. TODO


Gmail2Gcal by Neil Smithline is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.