Rewrite setup guide

ballerina-platform · Nov 28, 2023 · faef1cc · faef1cc
1 parent 0b5efc7
commit faef1cc
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -11,9 +11,23 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
 
-## Quickstart
+## Set up Gmail API
+
+To use the `gmail` connector, create Gmail credentials to interact with Gmail.
+
+1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1).
+
+2. **Enable Gmail API**: Enable the Gmail API for this project.
+
+3. **Configure OAuth consent**: Create a OAuth consent screen to display to the user.
 
-**Note**: Ensure you follow the [prerequisites](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-gmail-api) to set up the Gmail API.
+4. **Create OAuth client**: In the GCP console, create credentials for the OAuth client by configuring type and redirect url.
+
+5. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
+
+For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
+
+## Quickstart
 
 To use the `gmail` connector in your Ballerina application, modify the `.bal` file as follows:
 
@@ -45,13 +59,31 @@ gmail:Client gmailClient = check new gmail:Client(
 
 Now, utilize the available connector operations.
 
+#### Get unread emails in INBOX
+
 ```ballerina
 gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
-## Examples
+#### Send email
 
-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.
+```ballerina
+gmail:MessageRequest message = {
+    to: ["<recipient>"],
+    subject: "Scheduled Maintenance Break Notification",
+    bodyInHtml: string `<html>
+                            <head>
+                                <title>Scheduled Maintenance</title>
+                            </head>
+                        </html>`;
+};
+
+gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+```
+
+## Samples
+
+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.
 
 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.
@@ -65,20 +97,6 @@ The `gmail` connector provides practical examples illustrating usage in various
 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.
 
-For comprehensive information about the connector's functionality, configuration, and usage in Ballerina programs, refer to the `gmail` connector's reference guide in [Ballerina Central](https://central.ballerina.io/ballerinax/googleapis.gmail/latest).
-
-## Set up Gmail API
-
-To use the `gmail` connector, create Gmail credentials to interact with Gmail.
-
-1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1). Enable the Gmail API for this project.
-
-2. **Create OAuth client ID**: In the GCP console, create credentials for the OAuth client ID by setting up the OAuth consent screen.
-
-3. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
-
-For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
-
 ## 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](https://github.com/ballerina-platform/ballerina-library).

diff --git a/ballerina/Module.md b/ballerina/Module.md
@@ -4,9 +4,23 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
 
-## Quickstart
+## Set up Gmail API
+
+To use the `gmail` connector, create Gmail credentials to interact with Gmail.
+
+1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1).
+
+2. **Enable Gmail API**: Enable the Gmail API for this project.
+
+3. **Configure OAuth consent**: Create a OAuth consent screen to display to the user.
 
-**Note**: Ensure you follow the [prerequisites](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-gmail-api) to set up the Gmail API.
+4. **Create OAuth client**: In the GCP console, create credentials for the OAuth client by configuring type and redirect url.
+
+5. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
+
+For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
+
+## Quickstart
 
 To use the `gmail` connector in your Ballerina application, modify the `.bal` file as follows:
 
@@ -23,7 +37,7 @@ import ballerinax/googleapis.gmail;
 Create a `gmail:ConnectionConfig` with the obtained OAuth2.0 tokens and initialize the connector with it.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client (
+gmail:Client gmailClient = check new gmail:Client(
     config = {
         auth: {
             refreshToken,
@@ -38,13 +52,31 @@ gmail:Client gmailClient = check new gmail:Client (
 
 Now, utilize the available connector operations.
 
+#### Get unread emails in INBOX
+
 ```ballerina
 gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
-## Examples
+#### Send email
 
-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.
+```ballerina
+gmail:MessageRequest message = {
+    to: ["<recipient>"],
+    subject: "Scheduled Maintenance Break Notification",
+    bodyInHtml: string `<html>
+                            <head>
+                                <title>Scheduled Maintenance</title>
+                            </head>
+                        </html>`;
+};
+
+gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+```
+
+## Samples
+
+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.
 
 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.
@@ -57,17 +89,3 @@ The `gmail` connector provides practical examples illustrating usage in various
 
 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.
-
-For comprehensive information about the connector's functionality, configuration, and usage in Ballerina programs, refer to the `gmail` connector's reference guide in [Ballerina Central](https://central.ballerina.io/ballerinax/googleapis.gmail/latest).
-
-## Set up Gmail API
-
-To use the `gmail` connector, create Gmail credentials to interact with Gmail.
-
-1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1). Enable the Gmail API for this project.
-
-2. **Create OAuth client ID**: In the GCP console, create credentials for the OAuth client ID by setting up the OAuth consent screen.
-
-3. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
-
-For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
diff --git a/ballerina/Package.md b/ballerina/Package.md
@@ -4,9 +4,23 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
 
-## Quickstart
+## Set up Gmail API
+
+To use the `gmail` connector, create Gmail credentials to interact with Gmail.
+
+1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1).
+
+2. **Enable Gmail API**: Enable the Gmail API for this project.
+
+3. **Configure OAuth consent**: Create a OAuth consent screen to display to the user.
 
-**Note**: Ensure you follow the [prerequisites](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-gmail-api) to set up the Gmail API.
+4. **Create OAuth client**: In the GCP console, create credentials for the OAuth client by configuring type and redirect url.
+
+5. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
+
+For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
+
+## Quickstart
 
 To use the `gmail` connector in your Ballerina application, modify the `.bal` file as follows:
 
@@ -23,7 +37,7 @@ import ballerinax/googleapis.gmail;
 Create a `gmail:ConnectionConfig` with the obtained OAuth2.0 tokens and initialize the connector with it.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client (
+gmail:Client gmailClient = check new gmail:Client(
     config = {
         auth: {
             refreshToken,
@@ -38,13 +52,31 @@ gmail:Client gmailClient = check new gmail:Client (
 
 Now, utilize the available connector operations.
 
+#### Get unread emails in INBOX
+
 ```ballerina
 gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
-## Examples
+#### Send email
 
-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.
+```ballerina
+gmail:MessageRequest message = {
+    to: ["<recipient>"],
+    subject: "Scheduled Maintenance Break Notification",
+    bodyInHtml: string `<html>
+                            <head>
+                                <title>Scheduled Maintenance</title>
+                            </head>
+                        </html>`;
+};
+
+gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+```
+
+## Samples
+
+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.
 
 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.
@@ -58,20 +90,6 @@ The `gmail` connector provides practical examples illustrating usage in various
 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.
 
-For comprehensive information about the connector's functionality, configuration, and usage in Ballerina programs, refer to the `gmail` connector's reference guide in [Ballerina Central](https://central.ballerina.io/ballerinax/googleapis.gmail/latest).
-
-## Set up Gmail API
-
-To use the `gmail` connector, create Gmail credentials to interact with Gmail.
-
-1. **Create a Google Cloud Platform project**: Create a new project on [Google Cloud Platform (GCP)](https://console.cloud.google.com/getting-started?pli=1). Enable the Gmail API for this project.
-
-2. **Create OAuth client ID**: In the GCP console, create credentials for the OAuth client ID by setting up the OAuth consent screen.
-
-3. **Get the access token and refresh token**: Generate an access token and a refresh token using the OAuth playground.
-
-For detailed steps, including necessary links, refer to the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/docs/setup/setup.md).
-
 ## Report Issues
 
 To report bugs, request new features, start new discussions, view project boards, etc., go to the [Ballerina library parent repository](https://github.com/ballerina-platform/ballerina-library).