DEV Community: Goodness Chukwudi

How To Integrate Gmail API In Your Node.js Application

Goodness Chukwudi — Sat, 01 Jun 2024 17:02:12 +0000

The Gmail API provides a powerful and flexible solution for integrating Gmail's robust features into your app. With it, you can enable users to read, send, and organise their emails, manage drafts, labels and much more. This guide will walk you through the steps to seamlessly integrate the Gmail API, transforming your application into a centralised hub for email management.

Whether you’re developing a productivity tool, a customer relationship management (CRM) system, or any application that benefits from streamlined email interactions, this guide will equip you with the necessary knowledge and tools. We'll cover everything from setting up API access and handling authentication to implementing core email functionalities.

A more robust implementation of a Gmail client using Gmail APIs can be found here github.com/Goodness-Chukwudi/gmail-client.

Setting Up Your Gmail Project On Google Cloud Console

1. Create a project. To create and set up your project on Google cloud console, head over to console.cloud.google.com and sign in with your gmail account. From the project dropdown at the top left corner, create a new project or select an existing project if you have any.

After creating a project, select APIs and services from the navigation menu at the top left corner.

2. Enable Gmail APIs. Click on + ENABLE APIS AND SERVICES at the top of the page. This opens the API library page. Search for Gmail API select it and click on Enable to activate Gmail API.

3. Generate credentials for your app. To create the credentials you will use to connect from your app, click on Credentials in the sidebar under APIs and services and click on + CREATE CREDENTIALS at the top of the screen. Select OAuth Client ID, select Web application as application type and click Create. Copy the Client ID and Client secret; You will need it to connect to your Google project from your Node.js app.

4. OAuth screen Setup. You will be using OAuth to give your app access to a user’s mailbox. Select OAuth consent screen under Credentials and fill the name of the app, support email and other details. Don’t bother setting up the scopes, you will do that from your application. Once this is done, you will head to your system to write some code

Code Setup and API Integrations

This tutorial is meant for people with prior knowledge of Node.js already. Consequently, it guide does not cover installation and setup of a Node.js app.

1. Project setup and dependency installation. After setting up your Node.js project, on your terminal run npm i googleapis to install googleapis from npm. Add the credentials you created to your .env file: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GMAIL_REDIRECT_URL(during OAuth authentication, google will call this endpoint with the authentication code if successful). The redirect url needs to be a live url on your server's domain, but you can use ngrok to expose your localhost to the internet to enable us to get the redirect during OAuth authentication. Head over to ngrok.com and follow the instructions there to set up ngrok locally. Once you have set up ngrok, the redirect url should be in this format <your-ngrok-ur/a-route-of-your-choice>. Eg. https://my-url/call_back_path.

2. OAuth authentication. Create a file, say gmail_service.js for your Gmail API calls code. Import googleapis and initialise OAuth2 and Gmail client from googleapis. We will use nodemailer’s MailComposer to compose a MIME message for our emails. So go ahead and install nodemailer from npm: npm i nodemailer. You will be needing it later.



import { google } from "googleapis";
const MailComposer = require("nodemailer/lib/mail-composer");

const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.GMAIL_REDIRECT_URL
);

google.options({auth: oauth2Client})
const gmailClient = google.gmail('v1');

Setting the auth on the Gmail client with the OAuth client authenticates our app's request to our Google project.

3. Generate the consent page url using the OAuth2 client and open it on a browser to give access to the app. In a real world scenario, this url is returned to the front end part of your app. This enables the user to grant your app access to their email.



const scopes = [
    "https://www.googleapis.com/auth/gmail.labels",
    "https://www.googleapis.com/auth/gmail.modify",
  ];
  const url = oauth2Client.generateAuthUrl({
    access_type: "offline",
    scope: scopes,
    prompt: "consent"
});
console.log(url)

The scopes specifies the type of access and access level the app will request from the user. Refer to developers.google.com/gmail/api/auth/scopes for more on scopes.

4. Extract refresh token from auth code. You need to specify a route that matches the redirect url you specified in your application. This route must be a GET endpoint. Once the OAuth authentication is complete, Google will call your redirect url with the auth code in the request query. Extract the credentials from the returned code using the OAuth client. The extracted token is an object containing the refresh token among other fields. This refresh token should be saved in a secured place, preferably on your DB. This refresh token is sent alongside and validates every request to the API for this user.



import { Router } from "express";

const router = Router();
router.get("[path]", async (req, res) => {
    const code = req.query.code as string;
    const {tokens} = await oauth2Client.getToken(code)
    oauth2Client.setCredentials(tokens);
    console.log("refresh_token =========>  ", tokens.refresh_token);
})

Accessing Gmail APIs

Now that your Gmail client is set up and authenticated, you can now call Gmail’s API to manage an email's inbox, send email and much more. Go to developers.google.com/gmail/api/guides to see all available APIs and their usages.

1. Retrieving messages. The list method retrieves messages in the provided mailbox. me refers to the email of the user attached to the refresh token of a request. You can replace me with the actual email address.



function retrieveMessages() {
  const messagesResponse = await gmailClient.users.messages.list({userId: 'me'});
  const messages = messagesResponse.data.messages;
  console.log("messages =========>  ", messages);
}

await retrieveMessages();

2. Get one message.



function getOneMessage(messageId) {
  const messageResponse = await gmailClient.users.messages.get({userId: 'me', id: messageId});
  const message = messageResponse.data;

  let messageBody = "";
  const body = message.payload?.parts ? message.payload.parts[1].body : message.payload?.body;

  if (body?.data) {
    const buffer = Buffer.from(body.data, "base64");
    messageBody = buffer.toString("utf-8");
  } 

  //For messages with attachments
  if (body?.attachmentId) {
    const textPart = message.payload?.parts[0]?.parts[1]?.body?.data;
    if (textPart) {
      const buffer = Buffer.from(textPart, "base64");
      messageBody = buffer.toString("utf-8");
    }
  }

  console.log("message =========>  ", messageBody);
}

await getOneMessage(messageId);

3. List drafts. The list method lists the drafts in the provided mailbox.



function listDrafts() {
  const draftsResponse = await gmailClient.users.drafts.list({userId: 'me'});
  const drafts = draftsResponse.data.drafts;
  console.log("drafts =========>  ", drafts);
}

await listDrafts();

4. Get one draft



function getOneDraft(draftId) {
  const draftResponse = await gmailClient.users.drafts.get({userId: 'me', id: draftId});
  const draft = draftResponse.data;
  const payload = draft.message?.payload;

  let messageBody = "";
  const body = payload?.parts ? payload.parts[1].body : payload?.body;

  if (body?.data) {
    const buffer = Buffer.from(body.data, "base64");
    messageBody = buffer.toString("utf-8");
  } 

  //For drafts with attachments
  if (body?.attachmentId) {
    //@ts-ignore
    const textPart = payload?.parts[0]?.parts[1]?.body?.data;
    if (textPart) {
      const buffer = Buffer.from(textPart, "base64");
      messageBody = buffer.toString("utf-8");
    }
  }
  console.log("draft =========>  ", messageBody); 
}

await getOneDraft(draftId);

5. List labels.



function listLabels() {
  const labelsResponse = await gmailClient.users.labels.list({userId: 'me'});
  const labels = labelsResponse.data.labels;
  console.log("labels =========>  ", labels);
}

await listLabels();

6. Delete a message. A message is deleted by adding a TRASH label to it. Go to developers.google.com/gmail/api/guides/labels for more on message labels.



function deleteMessage(messageId) {
  await gmailClient.users.messages.trash({userId: 'me', id: messageId});
}

await deleteMessage(messageId);

7. Batch delete messages. To delete multiple messages at a go, add TRASH to the label of each message.



function deleteMessages(messageIds) {
  const requestBody = {ids: messageIds, addLabelIds: ["TRASH"]};
  await gmailClient.users.messages.batchModify({userId: 'me', requestBody});
}

await deleteMessages(messageIds);

8. Restore a deleted message.



function restoreMessage(messageId) {
  await gmailClient.users.messages.untrash({userId: 'me', id: messageId});
}

await restoreMessage(messageId);

9. Send mail. The email API accepts only MIME email messages that's compliant with RFC 2822 and encoded as a base64 string.



function encodeEmail(email) {
  const mail = new MailComposer({
      from: "me",
      to: email.recipient,
      cc: email.cc,
      html: email.body,
      subject: email.subject,
      textEncoding: "base64"
    });

    mail.compile().build((err, message) => {
      if (err) console.log(err);
      const encodedEmail = Buffer
        .from(message)
        .toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=+$/, '');

      return encodedEmail;
    });
}

function sendMessage(emailObject) {
  const requestBody = {
      raw: await encodeEmail(emailObject)
  }
  await gmailClient.users.messages.send({userId: "me", requestBody});
}

await sendMessage(emailObject);

10. Create drafts. Drafts represent an unsent message with the DRAFT label applied. The input will be the same with send email API inputs.



function createDraft(emailObject) {
  const requestBody = {
    raw: await encodeEmail()
  }

  await gmailClient.users.drafts.create({userId: 'me', requestBody});
}

await createDraft(emailObject);

11. Update drafts. Messages do not actually get updated. The update request instead, destroys the message attached to the draft you want to update and replaces it with a new message containing the new MIME message you sent.



function updateDraft(emailObject, draftId) {
  const requestBody = {
    raw: await encodeEmail()
  }

  await gmailClient.users.drafts.update({userId: 'me', id: draftId, requestBody});
}

await updateDraft(emailObject, draftId);

12. Delete drafts.



function deleteDraft(draftId) {
  await gmailClient.users.drafts.delete({userId: 'me', id: draftId});
}

await deleteDraft(draftId);

13. Send drafts.



function sendDraft(draftId) {
  const requestBody = {
    id: draftId
  }
  await gmailClient.users.drafts.send({userId: 'me', requestBody});
}

await sendDraft(draftId);

14. Revoke access. Though users can revoke access given to your application from their Gmail app, you can also give them a way to revoke the access from within your application using the revokeToken API.



function revokeAppAccess(refreshToken) {

  await oauth2Client.revokeToken(refreshToken);

}

await revokeAppAccess(refreshToken);

Conclusion

A full list and implementation guide for all the features available on the Gmail API is available on developers.google.com/gmail/api/guides.

What’s Next?

A more robust implementation of a Gmail client app, with user authentication management using Node.js and Express.js and MongoDB is available on github.com/Goodness-Chukwudi/gmail-client. Please leave a star on the repo if you find it helpful. Also feel free to raise a PR if you want to contribute more features or improve existing ones. Suggestions are welcomed as well. Reach me on ibechechukwudi@gmail.com

A step-by-step guide on how to create and publish an npm package

Goodness Chukwudi — Sat, 20 Apr 2024 05:26:47 +0000

If you are reading this, you are most likely either trying to publish a package to npm or just learning how to publish npm packages. No matter which one you fall into, I’m here to guide you through the steps to achieving that.

Introduction

NPM (Node Package Manager) is the world’s largest software registry. Open source developers from every continent use npm to share and borrow packages, and many organisations use npm to manage private development as well.

If you are a javascript developer, chances are that you are familiar with npm.
The scope of this article is publishing a package to npm and I will try to stick to that as much as possible. To seamlessly follow the steps outlined in this article and have a good understanding of the concepts used, you need to be familiar with javascript, node, git and npm. If you don’t have node installed, head over to the official website to download and install Node.js.

Step 1: Choose a name for your package.

To begin, you will need to choose a name for your package.
Note: Your package name must be unique. Using the exact or similar name of an existing package will return an error when publishing the package to npm. To ensure the uniquenesses of your package name, head over to npmjs.com and search for any existing packages with a similar name.
If there’s an exact match or a similar name, consider changing the name you will use for your package or publish your package as a scoped package. see “about scopes” for details.

The npm package we will be building for this article will be called boolean-converter, and aims to simplify the process of converting values to boolean in Node.js applications.
As developers working with Node.js, we often encounter scenarios where we need to interpret user input, API responses, or configuration values as boolean values. However, JavaScript's loose typing system can sometimes lead to unexpected results when dealing with truthy and falsy values.

Step 2: Create a project folder and make it a git repository.

Initialise git in your project folder. I will be using git and github (you can use a service of your choice) for version control. After creating a repository on github, in your computer’s terminal, navigate to the location you want to keep your project and clone the repository you just created using the command git clone <url of repository>.

git clone https://github.com/Goodness-Chukwudi/boolean-converter.git

Step 3: Initialise NPM in your project.

From your terminal, navigate to the root of your project folder and initialise npm using the command below 👇

npm init

You can initialise a scoped package by passing the scope flag to the command.

For an organisation-scoped package, replace my-org in the command below with the name of your organisation:

npm init --scope=@my-org

For a user-scoped package, replace my-username in the command below with your username:

npm init --scope=@my-username

You will get prompts requesting for

package name
version
description
entry point
test command
git repository
keywords
author
license

This will be used to create a package.json for your project. Provide the requested information or press enter to use the default for each prompt. See the image below👇

If successful, your project should have a package.json file with contents reflecting the information you provided. See the image below👇

Step 4: Write the code for your package

Create the additional files: converter.js, index.js in your project.

Copy and paste the cold below inside converter.js


    /**
     * Converts a value to boolean
     * - "1", true, "true", "on", "yes", 1 converts to true while every other value converts to false
     * - value is not case sensitive
     * @param value the value (of type string|boolean|number) to be converted
     * @returns  a boolean
    */
    const convertToBoolean = (value) => {
        try {

            if(value == undefined) throw new Error("No value provided");

            if (typeof value === "string") value = value.toLowerCase();
            const allowedTruthValues = ["1", "true", "on", "yes", 1, true];

            if (allowedTruthValues.includes(value)) return true;
            return false;

        } catch (error) {
            throw error;
        }
    }

module.exports = {convertToBoolean};

Copy and paste the code below inside index.js

const {convertToBoolean} = require("./converter")

module.exports = convertToBoolean

Step 5: Test your package

If you followed the previous steps correctly, your package should be ready now. To test it before publishing, create a new project; we will call it test-project. Initialise npm like we did in step 3. You can use default values all through as this is just for test purposes. Install your package in the test project using the npm install command: npm install <full path to your project>.

npm install /users/username/folder-path/more-folder-path/boolean-converter

This will create a node_modules folder with your package in it. Import the exported function from your package like every other npm package you have used and test to make sure everything works fine.

Step 6: Publishing your package to npm

Now that everything works as expected, we are going to publish the package to npm.

Login to npm on your terminal. Head to npmjs.com and create an account if you don’t have any yet.
From the root of your project on your terminal, run the command below

npm login

You will get a prompt to login via your browser, press enter and complete the sign in process.

Back to your terminal, use the command to publish your package to the public on npm registry.

npm publish

If everything goes well, your package will be published to npm and your terminal should have a response similar to the screenshot below. You can go the npm website and search for the package with its name.

Publishing Scoped Packages

By default, scoped packages are published with private visibility. To publish a scoped package with public visibility, pass the access flag when publishing the package.--access public.

npm publish --access public

Conclusion

If you followed along and everything worked fine, congratulations 🥂 , you have just published your first package to npm! 🥳

Providing tools that make common tasks easier for other developers is always valuable and a great way to contribute to the community. The magic becomes very obvious when you shared a more efficient way of getting things done.

Thank you for coming this far. The npm community await the amazing packages you will be publishing 🤝