ballerinax/ Ballerina library


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

The ballerinax/ package offers APIs to connect and interact with Gmail API endpoints.

Set up Gmail API

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

  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:

    Application typeWeb Application
    Authorized Redirect URIs
  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


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

Step 1: Import the connector

Import the ballerinax/ package into your Ballerina project.

import ballerinax/;

Step 2: Instantiate a new connector

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

gmail:Client gmailClient = check new gmail:Client(
    config = {
        auth: {

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Get unread emails in INBOX

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

Send email

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

gmail:Message sendResult = check gmailClient->/users/me/messages/;


The gmail connector provides practical examples illustrating usage in various scenarios. Explore these samples, 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 notifications Automatically send emails for scheduled maintenance breaks.

  3. Send automated response to emails Automate fetching unread emails from the Inbox and send personalized responses to customers.

  4. Search for relevant email threads Use the Gmail API to search for email threads based on a specific query.


import ballerinax/;Copy


Released date: 7 months ago

Version: 4.0.0

License: Apache-2.0


Platform: any

Ballerina version: 2201.8.4

GraalVM compatible: Yes

Pull count

Total: 10691

Current verison: 145

Weekly downloads

Source repository






Other versions

See more...