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.
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.
-
Open the Google Cloud Platform Console.
-
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.
-
Navigate to the Library tab and enable the Gmail API.
-
Click on the OAuth consent screen tab in the Google Cloud Platform console.
-
Provide a name for the consent application and save your changes.
-
Navigate to the Credentials tab in your Google Cloud Platform console.
-
Click on Create credentials and select OAuth client ID from the dropdown menu.
-
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 -
After filling in these details, click on Create.
-
Make sure to save the provided Client ID and Client secret.
Note: It is recommended to use the OAuth 2.0 playground to obtain the tokens.
-
Configure the OAuth playground with the OAuth client ID and client secret.
-
Authorize the Gmail APIs (Select all except the metadata scope).
-
Exchange the authorization code for tokens.
To use the gmail connector in your Ballerina application, modify the .bal file as follows:
Import the gmail module.
import ballerinax/googleapis.gmail;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
}
}
);Now, utilize the available connector operations.
gmail:MessageListPage messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");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);bal runThe gmail connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering use cases like sending emails, retrieving messages, and managing labels.
-
Process customer feedback emails - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
-
Send maintenance break emails - Send emails for scheduled maintenance breaks
-
Automated Email Responses - Retrieve unread emails from the Inbox and subsequently send personalized responses.
-
Email Thread Search Search for email threads based on a specified query.
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.
-
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_HOMEenvironment variable to the directory where JDK was installed. -
Download and install Ballerina Swan Lake.
-
Download and install Docker.
Note: Ensure that the Docker daemon is running before executing any tests.
Execute the commands below to build from the source.
-
To build the package:
./gradlew clean build
-
To run the tests:
./gradlew clean test -
To build the without the tests:
./gradlew clean build -x test -
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 -
To debug package with a remote debugger:
./gradlew clean build -Pdebug=<port>
-
To debug with the Ballerina language:
./gradlew clean build -PbalJavaDebug=<port>
-
Publish the generated artifacts to the local Ballerina Central repository:
./gradlew clean build -PpublishToLocalCentral=true
-
Publish the generated artifacts to the Ballerina Central repository:
./gradlew clean build -PpublishToCentral=true
As an open-source project, Ballerina welcomes contributions from the community.
For more information, go to the contribution guidelines.
All the contributors are encouraged to read the Ballerina Code of Conduct.
- For more information go to the
googleapis.gmailpackage. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.