FullStack Labs

Please Upgrade Your Browser.

Unfortunately, Internet Explorer is an outdated browser and we do not currently support it. To have the best browsing experience, please upgrade to Microsoft Edge, Google Chrome or Safari.
Upgrade

Accessing Mailbox Using the Gmail API and Node.js

Written by 
Oscar Justinico
,
Software Engineer
Accessing Mailbox Using the Gmail API and Node.js
blog post background
A Day in The Life of a Software Engineer at FullStack Labs
2020 Software Development Price Guide & Hourly Rate Comparison
How Company Culture Attracts Top IT Talent in Colombia

The Gmail API grants secure access to messages, threads, and labels and allows developers to create a variety of different applications for mail indexing, label management, and message sending.

In this tutorial, you will learn how to create a simple app that can grant access to a Gmail account, filter the list of messages, and assign them a specific label. The code shown here is written in Node.js but you can easily adapt it to your preferred language.

Create a Project in Google API Console

First, create a project in the Google Developers Console. Visit https://console.developers.google.com/ and log in, then click on Select a project > NEW PROJECT.

Google developer console

Enable the Gmail API Library

Navigate to the Library, search for the Gmail API and enable it.

Gmail API

Configure OAuth Consent Screen

Before creating the credentials, configure the OAuth consent screen by clicking on the button CONFIGURE CONSENT SCREEN.

OAuth Consent Screen

Select the User Type depending on the users who will be able to use the application.

External User Type

Type the application name and click Save.

OAuth Consent Screen

Create Credentials

In the left menu, click on Credentials > CREATE CREDENTIALS, and select OAuth client ID.

OAuth Client Id

Select the application type and enter a name for the credentials.

Create OAuth Client Id

You should be able to see the new credentials under the OAuth 2.0 Client IDs section. Click on the download icon to download the credentials file. Then rename it to credentials.json.

API Credentials

Set Up the QuickStart Example

Navigate to the Node.js Quickstart page, copy the quickstart example provided by Google, and save it in a file named index.js.

Gmail API Sample

In the Terminal window, go to the Working Directory where you created the file index.js, and run the command yarn add googleapis@39 to install the Gmail API library.

Then run the command node . to execute the sample code. The first time you will be asked to authorize the application by visiting a URL like the example below. Open that URL in a browser and follow the steps. At the end, you will get a code that you have to paste in the terminal window right where it says “Enter the code from that page here.”

-- CODE language-javascript keep-markup --
Authorize this app by visiting this url: https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly&response_type=code&client_id=479559853488-050lms0ffusprdhh938s954q0s36kg4i.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
Enter the code from that page here:

After the app is successfully authorized, a list of the current labels from the user’s mailbox is shown.

-- CODE language-javascript keep-markup --
Labels:- CATEGORY_PERSONAL
- CATEGORY_SOCIAL
- CATEGORY_UPDATES
- CATEGORY_FORUMS
- CATEGORY_PROMOTIONS
- CHAT
- SENT
- INBOX
- TRASH
- DRAFT
- SPAM
- STARRED
- UNREAD

Custom the Example Code

The authorize function in the quickstart example is in charge of validating the credentials and generating the token. You have to send the constant oAuth2Client as a parameter for the functions listed in the next sections.

-- CODE language-javascript keep-markup --
functionauthorize(credentials, callback) {  
  ...  
  const oAuth2Client = new google.auth.OAuth2(      
    client_id, client_secret, redirect_uris[0]);  
  ...
}

Now, in order to be able to manage the labels of the messages, you need to change the initial scope from gmail.readonly to gmail.modify.

-- CODE language-javascript keep-markup --
const SCOPES = ['https://www.googleapis.com/auth/gmail.modify'];

Also, delete the token.json file from your working directory.

Then, go to the listLabels function and add the label id in the console log.

-- CODE language-javascript keep-markup --
functionlistLabels(auth) {  
  ...      
    labels.forEach((label) => {        
      console.log(`- ${label.name} : ${label.id}`);      
    });  
  ...
}

Finally, run the application by using the command node . to authorize the app again and update the access permissions. You should be able to see the label list but now each label with its corresponding id.

-- CODE language-javascript keep-markup --
Labels:
- CATEGORY_PERSONAL : CATEGORY_PERSONAL
- CATEGORY_SOCIAL : CATEGORY_SOCIAL
- CATEGORY_UPDATES : CATEGORY_UPDATES
- CATEGORY_FORUMS : CATEGORY_FORUMS
- CATEGORY_PROMOTIONS : CATEGORY_PROMOTIONS
- CHAT : CHAT
- PENDING : Label_11
- SENT : SENT
- INBOX : INBOX
- TRASH : TRASH
- DRAFT : DRAFT
- SPAM : SPAM
- STARRED : STARRED
- UNREAD : UNREAD

List Messages

The list messages function uses the gmail.users.messages.list to list the messages that meet the criteria given by the query param.

-- CODE language-javascript keep-markup --
functionlistMessages(auth, query) {  
  return new Promise((resolve, reject) => {    
    const gmail = google.gmail({version: 'v1', auth});    
    gmail.users.messages.list(      
      {        
        userId: 'me',        
        q: query,      
      },      
      (err, res) => {        
        if (err) {          
          reject(err);          
          return;        
        }        
        if (!res.data.messages) {          
          resolve([]);          
          return;        
        }        
        resolve(res.data.messages);      
      }    
    );  
  })

;}

You can call this function as follows:

-- CODE language-javascript keep-markup --
const messages = await listMessages(oAuth2Client, 'label:inbox subject:reminder');

This will retrieve all messages from the inbox with a subject that includes the word “reminder.”

Modify Labels

You can modify the label of any message by using this function.

-- CODE language-javascript keep-markup --
functionmodifyLabels(auth, messageId, addLabelIds, removeLabelIds) {  
  returnnew Promise((resolve, reject) => {    
    const gmail = google.gmail({version: 'v1', auth});    
    gmail.users.messages.modify(      
      {        
        id: messageId,        
        userId: 'me',        
        resource: {          
          addLabelIds,          
          removeLabelIds,        
        },      
      },      
      (err, res) => {        
        if (err) {          
          reject(err);          
          return;        
        }        
        resolve(res);        
        return;      
      }    
    );  
  });

}

Loop through the previous messages. Call the modifyLabels functions with the right parameters.

This call will remove the INBOX label and will add the PENDING label to all the messages. Label_11 is the id of the label PENDING that we created using the Gmail site.

-- CODE language-javascript keep-markup --
messages.forEach(msg => {    
  modifyLabels(oAuth2Client, msg.id, [Label_11], ['INBOX']);
})

For sake of simplicity, we created and retrieved the id of the PENDING label manually. However, the Gmail API provides the methods that will let you do that programmatically. We encourage you to check the API Reference by visiting Gmail API Documentation.

Let us know how you did!

Conclusion

Using techniques like what is listed above, we have had the opportunity to address our clients’ concerns and they love it! If you are interested in joining our team, please visit our Careers page.

---
At FullStack Labs, we are consistently asked for ways to speed up time-to-market and improve project maintainability. We pride ourselves on our ability to push the capabilities of these cutting-edge libraries. Interested in learning more about speeding up development time on your next form project, or improving an existing codebase with forms? Contact us.

Oscar Justinico
Written by
Oscar Justinico
Oscar Justinico

As a Software Engineer at FullStack Labs, I’m focused on developing high-quality applications using React Native. Prior to FullStack Labs, I was a Senior Software Developer at CodeLabs where I contributed to the development of numerous applications using JavaScript, React and PHP. I hold a degree in Mechatronics Engineering from the National University of Colombia.

FullStack Labs Icon

Let's Talk!

We’d love to learn more about your project. Contact us below for a free consultation with our CEO.
Projects start at $50,000.

company name
name
email
phone
Type of project
Reason for contact
How did you hear about us?
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.