Skip to content

ballerina-platform/module-ballerinax-googleapis.gmail

Repository files navigation

Ballerina Gmail Connector

Build Trivy codecov GraalVM Check GitHub Last Commit GitHub Issues

Gmail is a widely-used email service provided by Google LLC, enabling users to send and receive emails over the internet.

The ballerinax/googleapis.gmail package offers APIs to connect and interact with Gmail API endpoints, specifically based on Gmail API v1.

Setup guide

To use the Gmail connector, you must have access to the Gmail REST API through a Google Cloud Platform (GCP) account and a project under it. If you do not have a GCP account, you can sign up for one here.

Step 1: Create a Google Cloud Platform project

  1. Open the Google Cloud Platform Console.

  2. Click on the project drop-down menu and select an existing project or create a new one for which you want to add an API key.

    GCP Console Project View

Step 2: Enable Gmail API

  1. Navigate to the Library tab and enable the Gmail API.

    Enable Gmail API

Step 3: Configure OAuth consent

  1. Click on the OAuth consent screen tab in the Google Cloud Platform console.

    Consent Screen
  2. Provide a name for the consent application and save your changes.

Step 4: Create OAuth client

  1. Navigate to the Credentials tab in your Google Cloud Platform console.

  2. Click on Create credentials and select OAuth client ID from the dropdown menu.

    Create Credentials
  3. You will be directed to the Create OAuth client ID screen, where you need to fill in the necessary information as follows:

    Field Value
    Application type Web Application
    Name GmailConnector
    Authorized Redirect URIs https://developers.google.com/oauthplayground
  4. After filling in these details, click on Create.

  5. Make sure to save the provided Client ID and Client secret.

Step 5: Get the Access and Refresh token

Note: It is recommended to use the OAuth 2.0 playground to obtain the tokens.

  1. Configure the OAuth playground with the OAuth client ID and client secret.

    OAuth Playground
  2. Authorize the Gmail APIs (Select all except the metadata scope).

    Authorize APIs
  3. Exchange the authorization code for tokens.

    Exchange Tokens

Quickstart

To use the gmail connector in your Ballerina application, modify the .bal file as follows:

Step 1: Import the module

Import the gmail module.

import ballerinax/googleapis.gmail;

Step 2: Instantiate a new connector

Create a gmail:ConnectionConfig with the obtained OAuth2.0 tokens and initialize the connector with it.

configurable string refreshToken = ?;
configurable string clientId = ?;
configurable string clientSecret = ?;

gmail:Client gmail = check new gmail:Client(
    config = {
        auth: {
            refreshToken,
            clientId,
            clientSecret
        }
    }
);

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Get unread emails in INBOX

gmail:MessageListPage messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");

Send email

gmail:MessageRequest message = {
    to: ["<recipient>"],
    subject: "Scheduled Maintenance Break Notification",
    bodyInHtml: string `<html>
                            <head>
                                <title>Scheduled Maintenance</title>
                            </head>
                        </html>`;
};

gmail:Message sendResult = check gmail->/users/me/messages/send.post(message);

Step 4: Run the Ballerina application

bal run

Examples

The gmail connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering use cases like sending emails, retrieving messages, and managing labels.

  1. Process customer feedback emails - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.

  2. Send maintenance break emails - Send emails for scheduled maintenance breaks

  3. Automated Email Responses - Retrieve unread emails from the Inbox and subsequently send personalized responses.

  4. Email Thread Search Search for email threads based on a specified query.

Issues and projects

The Issues and Projects tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc., visit the Ballerina library parent repository.

This repository only contains the source code for the package.

Build from the source

Prerequisites

  1. Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:

    Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.

  2. Download and install Ballerina Swan Lake.

  3. Download and install Docker.

    Note: Ensure that the Docker daemon is running before executing any tests.

Build options

Execute the commands below to build from the source.

  1. To build the package:

    ./gradlew clean build
  2. To run the tests:

    ./gradlew clean test
  3. To build the without the tests:

    ./gradlew clean build -x test
  4. To run tests against different environment:

    ./gradlew clean test -Pgroups=<Comma separated groups/test cases>

    Tip: The following groups of test cases are available.

    Groups Environment
    mock Mock server
    gmail Gmail API
  5. To debug package with a remote debugger:

    ./gradlew clean build -Pdebug=<port>
  6. To debug with the Ballerina language:

    ./gradlew clean build -PbalJavaDebug=<port>
  7. Publish the generated artifacts to the local Ballerina Central repository:

    ./gradlew clean build -PpublishToLocalCentral=true
  8. Publish the generated artifacts to the Ballerina Central repository:

    ./gradlew clean build -PpublishToCentral=true

Contribute to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links