A crucial part of programming is the ability to communicate with different Application Programming Interfaces (APIs). If you visit Google API Explorer, you will find a huge library of APIs, including all of their well-known applications like Gmail, Drive, and Calendar. Simply put, an API allows you to fetch or send data to the services via HTTP requests.

The usage and documentation of these APIs might be a bit tricky at first, but once you learn it, you‘ll be able to apply your knowledge to most Google applications.

I decided to write a beginner’s guide for how to use and understand the Gmail API. The guide is based on the documentation, meaning you’ll learn what to look for and how to read it instead of just copying code. As most of the other Google API references documents are alike, you’ll see that adapting to them is much easier once you know how to actually read the docs. This will allow you to write your own code and actually understand what you’re doing.

Python 3 is used in this guide, but the usage should look quite similar in other languages as well.

Quickstart

Google usually offers a quickstart guide to make authorization easier. This guide will use the authorization from the quickstart guide, which means it’ll come with some limitations, but it’s sufficient for our purposes. The other way to get the API key is to create a new project, which is a bit trickier.

The Python quickstart guide can be accessed at this link, but I’ll follow along and show you how everything is done here.

Here’s what the quickstart looks like:

Turn on the Gmail API

The first step is to enable the API and download the credentials to use in our project. By pressing the “enable the Gmail API” button, we open a new window with our credentials.

Our Client ID and Client Secret will be shown. Choose the client configuration for download. A file will be saved, called credentials.json . We’ll save this to the same folder our code will be in.

Installing the Libraries

Installing the required libraries is done with a simple pip command, provided by Google. I pasted it below as well. I would recommend doing it in a virtual environment. That is, however, not covered in this guide.

pip install — upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

First Run — Allow Access

Before we continue following the guide, we’ll need to allow access to the Gmail API for our script. Let’s start by making the actual script.

Create a .py file in the project directory (same as the directory with credentials.json ). For the sake of it, let’s call it gmail.py .

Copy the example code from the Python quickstart to the gmail.py file. Ignore the code for now, we’ll dive into that later. We only need to allow access on the first run — it will be saved for all later runs as well.

Just run the file as you normally would, and you’ll be able to sign in to your Google account in the web browser.

python gmail.py

Login to your account. A warning saying that the app is not verified will be shown. As we are using the quickstart method, our app is not yet verified. Just click the link shown on the picture to continue for now and allow access.