In this quick and easy Raspberry Pi project, you'll learn how to make a Gmail email notification light. If you have any unread emails, a Python script turns the LED on. This project requires very few parts, and can be completed in under an hour! You can of course dress up your LED any way you like, such as a MineCraft redstone block, or other object 3D printed in clear plastic. Here's the end result:

What You Need

  • 1 x Raspberry Pi
  • 1 x breadboard
  • 1 x 220 ohm resistor
  • 1 x 5mm LED
  • 1 x Gmail account
  • Male to female hook up wires

Any Raspberry Pi will work for this project -- even the Pi Zero! Only one GPIO pin is needed, and it's not particularly CPU intensive. If you have a Pi starter kit you have more than enough parts to complete this.

Build Plan

Gmail-Notification-LED

This is a really simple project. A Light Emitting Diode (LED) is connected to a GPIO (General Purpose Input Output) Pin on the Pi. A very simple Python script will run regularly to check to unread emails and turn the LED on or off accordingly.

The Hardware

Gmail-Notification-Circuit

Connect the positive anode (long leg) of the LED to the resistor and then to GPIO pin 14. You could use any GPIO pin, however look at the pinout first, as they vary slightly between models. Connect the negative cathode (short leg with flat edge) to ground.

Pi Setup

Gmail-Notification-Pi

Providing your Pi has an operating system (OS) installed there's not a lot of setup needed (not sure what you need? Learn how to install one here). Open a new terminal (Top left > menu > Accessories > Terminal) on the Pi (checkout these shortcuts to make you a coding ninja). You need to create a new folder to store the Python script. Enter the follow command: 

        pwd

This stands for "Print Working Directory", and will show you what folder you are in (by default this be "/home/pi"). Navigate into the documents folder and create a new directory (folder) called "gmail_python": 

        cd Documents/
sudo mkdir gmail_python

The "mkdir" command stands for "Make Directory". Anything following this will be used for the directory name. You should now be able to see your directory: 

        ls

If you made a mistake, you can easily remove this directory: 

        sudo rm -r gmail_python

Now navigate into the new directory: 

        cd gmail_python/

Create a new Python script: 

        sudo nano check_messages.py

This will create the script and open it ready for editing in Nano. You could of course use another program, such as Vim, although this tweet sums up my feelings about that:

Joking aside, check out this comparison between the two for a full breakdown.

Press CTRL + X to exit Nano and get back to the terminal.

Python Setup

Gmail-Notification-Code

Now that the Pi is setup, it's time to write the code. This project requires the excellent Gmail Python Library by Charlie Guo. Download the library from Github and extract the contents. Inside there should be a folder called "gmail". Copy this whole folder into "/home/pi/Documents/gmail_python".

Switch back to the command line and open your script again (if you press the up key you can scroll through your previously entered commands): 

        sudo nano check_messages.py

Notice how that is the same command you used to create the file -- if a file already exists it will be opened, otherwise it will be created. Here's the Python: 

        import gmail, RPi.GPIO as GPIO, time # import modules

GPIO.setwarnings(False)
GPIO.setmode(GPIO.BCM) # tell the Pi what headers to use
GPIO.setup(14, GPIO.OUT) # tell the Pi this pin is an output

g = gmail.login('YOUREMAIL@gmail.com', 'YOUR PASSWORD')
unread_messages = g.inbox().mail(unread=True)
total_messages = 0

for message in unread_messages:
	total_messages += 1

if total_messages > 0:
	# there are unread emails, turn light on
	GPIO.output(14, True)
else:
	# there are no unread emails, turn light off
	GPIO.output(14, False)

You will need to enter your username and password for this to work. You can view the full source code for the gmail plugin if you would like to. If you do not feel comfortable doing this (or you are using two-factor authentication) you will need to connect to Gmail using OAuth2. This is a bit involved for this tutorial, however Google has an excellent getting started guide.

Let's breakdown the code. First some modules are imported. Modules in Python are small pieces of code written for a purpose (similar to libraries in the Arduino IDE). RPi.GPIO is a Pi specific module for accessing the GPIO, gmail is the module you downloaded previously, and time is a module built into Python to provide timing functions. Now "GPIO.setmode" and "GPIO.setup" are used to tell the Pi that pin 14 is an output, and that you want to use "Broadcom Pin Numbering" (more information about BCM).

This line connects to your gmail account. It creates an object called "g", and calls the login method of the gmail module imported previously. Don't forget to enter your gmail email and password. 

        g = gmail.login('YOUREMAIL@gmail.com', 'YOUR PASSWORD')

Now retrieve all the unread messages and store them in a variable called "unread messages": 

        unread_messages = g.inbox().mail(unread=True)

Notice how "unread=True" is passed as a parameter -- you can change this to retrieve messages based on different parameters, such as sender or subject. Check out the Application Programming Interface (API) documentation for lots more information.

Next, a for loop is used to loop over every message: 

        for message in unread_messages:
	total_messages += 1

For loops are very useful. They repeat a block of code several times, often with a slightly different value each time. This for loop goes over every message in unread_messages and increments the "total_messages" variable.

Finally, some simple "if" statements are used. If there are unread messages, turn the LED on, otherwise turn if off.

Remember that Python is case sensitive, and uses white spacing. If you are having problems getting the code to run, try this website. Paste your Python in and press the "validate above python code" button. This should then tell you what (if any) errors are present in your Python.

Switch to the Terminal and run your script: 

        python check_messages.py

This command will run your script. Try manually changing some emails in your inbox to unread status and running the script again -- you should see the LED turn on or off to reflect your inbox.

Cron Setup

Now that the script works it's time to automate it. The easiest way to do this is through a cron job. Cron jobs are used to schedule tasks and scripts, such as automated backups. Open the Crontab (list of scheduled tasks): 

        crontab -e

If there are no scheduled tasks already setup, this file will be empty (it may contain documentation or comments, preceded by a "#"). If you already have entries in here, simply enter your new command on a new line: 

        * * * * * python ~/pi/Documents/gmail_python/check_messages.py

The five "stars" ("* * * * *") specify how often to run the task (you can get really fancy here, e.g. every second Wednesday at 2.00). These five stars specify that the task should be run every minute. This is the smallest interval allowed (learn more about cronjob scheduling). Next, "python" tells the scheduler to execute the script as a python file. Finally, "~/pi/Documents/gmail_python/check_messages.py" is the absolute file path to your script -- a relative path will not work.

You should now have your own Gmail notification light! It would be quite simple to modify this to look for messages based on a different requirement or filter (learn how to use filters here), or execute a different piece of code -- maybe you could create a Twitter bot that tweets based on emails (learn more about building a Pi Twitter bot).

However you end up coding your notification box, I'd love to know how it goes in the comments!