Why is Google’s documentation so unclear? Sending an email with the Gmail API

3 min readMar 13, 2023

Despite being the biggest tech company in the world and having tons of developers using its APIs, Google’s documentation is too often unclear and confusing.

Here’s a simple tutorial of how to send an email with the Gmail API.

Getting started

In this tutorial, we will create a Python function that takes an email address, a subject line and a body and sends an email to that address.

The first thing we might try is to look at the documentation. A quick search gives these results:

If you actually read the documentation, you’ll find that it’s not very helpful. The code examples never cover the whole process and the code samples are either too vague or too specific:

Thanks for the short snippet, Google! Also, I wanted to send an email, why do you create a draft?

Creating a Google Cloud project

To get started, you first need to create a new project in the Google Cloud Console (you should find a “New Project” button in the list of your projects).

The app you create is what will access your Gmail account and send emails.

Next, you need to enable the Gmail API. You can do that on your project’s API and Services page. Simply select Enable APIs and Services and search for “Gmail API”.

Finally, create an OAuth client for your code. This will give you credentials (an ID and a secret) to access your project programmatically. You can do that on your project’s Credentials page.

When you’re done, you should have a json file with your an ID and a secret. You’ll need those later.

A few notes:

You’ll have to configure your consent screen. This is simply the screen that your users (you and your testing address) will see when granting access to your app. The console will prompt you to do that.
In the beginning, your app will be in “Testing” mode. Don’t forget to add the email address you want to send emails from to the list of “Test users” on the OAuth consent screen page.

Python dependencies

You’ll need to install three dependencies to get started. You can do that with pip:

pip install oauth2client google_auth_oauthlib google-api-python-client

This will ensure you can get a refresh token (google_auth_oauthlib), authenticate yourself (oauth2client) and send emails (google-api-python-client).

Setting up the code

Now that we have everything set up, we can start writing some code. Since we will only be sending emails from a single address, we simply need to grant access to our app once. We can do that by running this quickstart code.

Running get_refresh_token() will open a page to grant access to your app. Once completed, it should give you a refresh token, that you can use to get an access token, which you can use to send emails (finally!).

Store the refresh token somewhere safe (like a .env file).

Now, let’s create two helper functions. The first one will simply create a MIMEText message.

The second one will use the refresh token to get an access token. Don’t forget to add your credentials to your .env file and to load it.

Sending an email

Finally, we can write the function that will send an email.

Easy, right? This should be enough to get you started. If you have any questions, feel free to ask in the comments.

Thanks!

Still reading? You must be pretty good at paying attention!

I would love to hear your feedback on my other projects, so feel free to look at my GitHub ;)

Thanks for reading and happy coding!