Make a Raspberry Pi Gmail Notification Light

Joe Coburn 30-08-2016

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

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

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

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 How to Install an Operating System on a Raspberry Pi Here's how to install an OS on your Raspberry Pi and how to clone your perfect setup for quick disaster recovery. Read More ). Open a new terminal (Top left > menu > Accessories > Terminal) on the Pi (checkout these shortcuts to make you a coding ninja Save Time in the Linux Terminal with These 20 Shortcuts Whether you're a terminal newbie or someone who got over the fear long ago, here are 20 shortcuts that can help you overcome some of the command line's awkwardness. Read More ). You need to create a new folder to store the Python script. Enter the follow command:


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:


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

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 nano vs. Vim: The Best Terminal Text Editors, Compared Looking for a terminal text editor for Linux? The main choice is between Vim and nano! Here's how they compare. Read More for a full breakdown.

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


Python Setup

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

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.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('', '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)
	# 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('', '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:


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/

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 How to Schedule Tasks in Linux with Cron and Crontab The ability to automate tasks is one of those futuristic technologies that is already here. Every Linux user can benefit from scheduling system and user tasks, thanks to cron, an easy-to-use background service. Read More ). Next, “python” tells the scheduler to execute the script as a python file. Finally, “~/pi/Documents/gmail_python/” 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 10 Email Problems You Can Solve with Gmail Filters An overflowing inbox driving you crazy? Do you want to through your inbox faster than ever? Try some of these brilliant Gmail filters to see the difference. Read More ), 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 How to Build a Raspberry Pi Twitter Bot Twitter is the world biggest repository of short messages from people with nothing to say - and now you too can contribute to that epic project with an automated Twitter bot, powered by your Raspberry... Read More ).

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

Related topics: Gmail, Raspberry Pi.

Affiliate Disclosure: By buying the products we recommend, you help keep the site alive. Read more.

Whatsapp Pinterest

Leave a Reply

Your email address will not be published. Required fields are marked *

  1. Travis Roderick
    February 15, 2017 at 11:25 pm

    Will this work with 2-Factor Authentication?

  2. Martin
    December 19, 2016 at 2:59 am

    Hello ! Great project ! The script works flawlessly when I run it from the command line but it does not when it is called by the cronjob. Why ? Thanks in advance for the help !

    • rax
      March 29, 2020 at 3:29 pm

      the cronjob should be
      `* * * * * python ~/Documents/gmail_python/`

      basically just remove the pi directory from it, as the ~ already indicates that is where you want it to run.

  3. Martin
    December 19, 2016 at 2:56 am

    Hello ! Great project ! I want to use something like this to have Raspberry Pi read my emails and do stuff while I'm away. So far, with the scripts above and some tweaking, every thing works just fine: Raspberry Pi can get the subject from unread emails and then mark them as read. However, when I try running the same script with a cron job it's as if GMail won't let me access the account. But why ? It works flawlessly when I run the very same script from the command line ! Thanks in advance for the help.

    • Gary
      January 19, 2019 at 8:19 pm

      Can you tell me how to test for a specific SUBJECT of an email?