diff --git a/.github/workflows/dev-stage-release.yml b/.github/workflows/dev-stage-release.yml index 278274a9..6e2cdfbb 100644 --- a/.github/workflows/dev-stage-release.yml +++ b/.github/workflows/dev-stage-release.yml @@ -19,4 +19,4 @@ jobs: secrets: inherit with: environment: ${{ github.event.inputs.environment }} - additional-publish-flags: "-x :googleapis.gmail-examples:build -Pgroups=mock" + additional-publish-flags: "-x :googleapis.gmail-examples:build" diff --git a/README.md b/README.md index 5de234b2..fafee670 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ [Gmail](https://blog.google/products/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](https://developers.google.com/gmail/api/guides) endpoints. +The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1). -## Set up Gmail API +## Set up guide To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/). @@ -127,21 +127,18 @@ gmail:MessageRequest message = { gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message); ``` -## Samples +## Examples -The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. +The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. -1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. +1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. -2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal) - Automatically send emails for scheduled maintenance breaks. +2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks -3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal) - Automate fetching unread emails from the Inbox and send personalized responses to customers. +3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses. -4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal) - Use the Gmail API to search for email threads based on a specific query. +4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads) + Search for email threads based on a specified query. ## Issues and projects diff --git a/ballerina/Module.md b/ballerina/Module.md index 16d264d4..20da6392 100644 --- a/ballerina/Module.md +++ b/ballerina/Module.md @@ -1,10 +1,10 @@ -# Overview +## Overview [Gmail](https://blog.google/products/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](https://developers.google.com/gmail/api/guides) endpoints. +The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1). -## Set up Gmail API +## Set up guide To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/). @@ -120,18 +120,15 @@ gmail:MessageRequest message = { gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message); ``` -## Samples +## Examples -The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. +The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. -1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. +1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. -2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal) - Automatically send emails for scheduled maintenance breaks. +2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks -3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal) - Automate fetching unread emails from the Inbox and send personalized responses to customers. +3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses. -4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal) - Use the Gmail API to search for email threads based on a specific query. +4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads) + Search for email threads based on a specified query. diff --git a/ballerina/Package.md b/ballerina/Package.md index 1743decc..c1f3aca8 100644 --- a/ballerina/Package.md +++ b/ballerina/Package.md @@ -1,10 +1,10 @@ -# Package overview +## Package overview [Gmail](https://blog.google/products/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](https://developers.google.com/gmail/api/guides) endpoints. +The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1). -## Set up Gmail API +## Set up guide To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/). @@ -120,21 +120,18 @@ gmail:MessageRequest message = { gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message); ``` -## Samples +## Examples -The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. +The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. -1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. +1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. -2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal) - Automatically send emails for scheduled maintenance breaks. +2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks -3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal) - Automate fetching unread emails from the Inbox and send personalized responses to customers. +3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses. -4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal) - Use the Gmail API to search for email threads based on a specific query. +4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads) + Search for email threads based on a specified query. ## Report Issues diff --git a/changelog.md b/changelog.md index 9db9ca20..56c26a7d 100644 --- a/changelog.md +++ b/changelog.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Improve documentation + ### Changed ## [4.0.0] - 2023-12-01 diff --git a/examples/README.md b/examples/README.md index ec7174dc..5b110d54 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,21 +2,18 @@ The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels. -1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. +1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read. -2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal) - Automatically send emails for scheduled maintenance breaks. +2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks -3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal) - Automate fetching unread emails from the Inbox and send personalized responses to customers. +3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses. -4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal) - Use the Gmail API to search for email threads based on a specific query. +4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads) + Search for email threads based on a specified query. ## Prerequisites -1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-gmail-api) to set up the Gmail API. +1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-guide) to set up the Gmail API. 2. For each example, create a `config.toml` file with your OAuth2 tokens, client ID, and client secret. Here's an example of how your `config.toml` file should look: diff --git a/examples/process-mails/.github/README.md b/examples/process-mails/.github/README.md new file mode 120000 index 00000000..2d4eed6d --- /dev/null +++ b/examples/process-mails/.github/README.md @@ -0,0 +1 @@ +../Process customer feedback emails.md \ No newline at end of file diff --git a/examples/process-mails/Process customer feedback emails.md b/examples/process-mails/Process customer feedback emails.md new file mode 100644 index 00000000..c4227cf2 --- /dev/null +++ b/examples/process-mails/Process customer feedback emails.md @@ -0,0 +1,29 @@ +# Process customer feedback emails + +This example demonstrates how to efficiently manage customer feedback emails. The Ballerina programme retrieves unread messages from the INBOX, extracts sender and subject information, and stores it in a CSV file for later access. + +## Prerequisites + +### 1. Set up Gmail API + +Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens). + +### 2. Configuration + +Configure Gmail API credentials in `Config.toml` in the example directory: + +```toml +refreshToken="" +clientId="" +clientSecret="" +``` + +## Run the Example + +Execute the following command to run the example: + +```bash +bal run +``` + +Check the results in the generated `feedback.csv` file. diff --git a/examples/reply-mails/.github/README.md b/examples/reply-mails/.github/README.md new file mode 120000 index 00000000..4754a120 --- /dev/null +++ b/examples/reply-mails/.github/README.md @@ -0,0 +1 @@ +../Automated Email Responses.md \ No newline at end of file diff --git a/examples/reply-mails/Automated Email Responses.md b/examples/reply-mails/Automated Email Responses.md new file mode 100644 index 00000000..b02181a2 --- /dev/null +++ b/examples/reply-mails/Automated Email Responses.md @@ -0,0 +1,27 @@ +# Automated Email Responses + +This example demonstrates the automated retrieval of unread emails from the Inbox and the subsequent sending of personalized responses. + +## Prerequisites + +### 1. Set up Gmail API + +Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens). + +### 2. Configuration + +Configure Gmail API credentials in `Config.toml` in the example directory: + +```toml +refreshToken="" +clientId="" +clientSecret="" +``` + +## Run the Example + +Execute the following command to run the example: + +```bash +bal run +``` diff --git a/examples/search-threads/.github/README.md b/examples/search-threads/.github/README.md new file mode 120000 index 00000000..b73a9b56 --- /dev/null +++ b/examples/search-threads/.github/README.md @@ -0,0 +1 @@ +../Email Thread Search.md \ No newline at end of file diff --git a/examples/search-threads/Email Thread Search.md b/examples/search-threads/Email Thread Search.md new file mode 100644 index 00000000..88c1bb3c --- /dev/null +++ b/examples/search-threads/Email Thread Search.md @@ -0,0 +1,27 @@ +# Email thread search + +This example showcases an efficient method to search for email threads based on a specified query. The code extracts and displays the subject and snippet of the first message in each relevant thread for streamlined information retrieval. + +## Prerequisites + +### 1. Set up Gmail API + +Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens). + +### 2. Configuration + +Configure Gmail API credentials in `Config.toml` in the example directory: + +```toml +refreshToken="" +clientId="" +clientSecret="" +``` + +## Run the Example + +Execute the following command to run the example: + +```bash +bal run +``` diff --git a/examples/send-mails/.github/README.md b/examples/send-mails/.github/README.md new file mode 120000 index 00000000..3147f91d --- /dev/null +++ b/examples/send-mails/.github/README.md @@ -0,0 +1 @@ +../Send Maintenance Break Emails.md \ No newline at end of file diff --git a/examples/send-mails/Send Maintenance Break Emails.md b/examples/send-mails/Send Maintenance Break Emails.md new file mode 100644 index 00000000..71ac0b1d --- /dev/null +++ b/examples/send-mails/Send Maintenance Break Emails.md @@ -0,0 +1,28 @@ +# Send maintenance break emails + +This example demonstrates the automated sending of emails for scheduled maintenance breaks. + +## Prerequisites + +### 1. Set up Gmail API + +Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens). + +### 2. Configuration + +Configure Gmail API credentials in `Config.toml` in the example directory: + +```toml +refreshToken="" +clientId="" +clientSecret="" +recipient="" +``` + +## Run the Example + +Execute the following command to run the example: + +```bash +bal run +```