|
| 1 | +Connects to Gmail from Ballerina. |
| 2 | + |
| 3 | +## Module Overview |
| 4 | + |
| 5 | +Ballerina Gmail Connector provides the capability to send, read and delete emails through the Gmail REST API. It also provides the ability to read, trash, untrash and delete threads, ability to get the Gmail profile and mailbox history, etc. The connector handles OAuth 2.0 authentication. |
| 6 | + |
| 7 | +## Configurations |
| 8 | + |
| 9 | +Instantiate the connector by giving authentication details in the Gmail client config, which has built-in support for OAuth 2.0. Gmail uses OAuth 2.0 to authenticate and authorize requests. The Gmail connector can be minimally instantiated in the Gmail client config using the Access Token or by using the Client ID, Client Secret and Refresh Token. |
| 10 | + |
| 11 | +**Obtaining Tokens to Run the Sample** |
| 12 | + |
| 13 | +1. Visit [Google API Console](https://console.developers.google.com), click **Create Project**, and follow the wizard to create a new project. |
| 14 | +2. Go to **Credentials -> OAuth Consent Screen**, enter a product name to be shown to users, and click **Save**. |
| 15 | +3. On the **Credentials** tab, click **Create Credentials** and select **OAuth Client ID**. |
| 16 | +4. Select an application type, enter a name for the application, and specify a redirect URI (enter https://developers.google.com/oauthplayground if you want to use |
| 17 | +[OAuth 2.0 Playground](https://developers.google.com/oauthplayground) to receive the Authorization Code and obtain the |
| 18 | +Access Token and Refresh Token). |
| 19 | +5. Click **Create**. Your Client ID and Client Secret will appear. |
| 20 | +6. In a separate browser window or tab, visit [OAuth 2.0 Playground](https://developers.google.com/oauthplayground). Click on the `OAuth 2.0 Configuration` |
| 21 | + icon in the top right corner and click on `Use your own OAuth credentials` and provide your `OAuth Client ID` and `OAuth Client Secret`. |
| 22 | +7. Select the required Gmail API scopes from the list of API's, and then click **Authorize APIs**. |
| 23 | +8. When you receive your authorization code, click **Exchange authorization code for tokens** to obtain the refresh token and access token. |
| 24 | + |
| 25 | +You can now enter the credentials in the Gmail client config. |
| 26 | + |
| 27 | +```ballerina |
| 28 | +gmail:GmailConfiguration gmailConfig = { |
| 29 | + oauthClientConfig: { |
| 30 | + accessToken: <ACCESS_TOKEN>, |
| 31 | + refreshConfig: { |
| 32 | + refreshUrl: gmail:REFRESH_URL, |
| 33 | + refreshToken: <REFRESH_TOKEN>, |
| 34 | + clientId: <CLIENT_ID>, |
| 35 | + clientSecret: <CLIENT_SECRET> |
| 36 | + } |
| 37 | + } |
| 38 | +}; |
| 39 | +
|
| 40 | +gmail:Client gmailClient = new (gmailConfig); |
| 41 | +``` |
| 42 | + |
| 43 | +## Compatibility |
| 44 | + |
| 45 | +| Ballerina Language Versions | Gmail API Version | |
| 46 | +|:----------------------------:|:-----------------:| |
| 47 | +| Swan Lake Preview7 | v1 | |
| 48 | + |
| 49 | +## Sample |
| 50 | + |
| 51 | +```ballerina |
| 52 | +import ballerina/io; |
| 53 | +import ballerinax/googleapis.gmail; |
| 54 | +
|
| 55 | +gmail:GmailConfiguration gmailConfig = { |
| 56 | + oauthClientConfig: { |
| 57 | + accessToken: <ACCESS_TOKEN>, |
| 58 | + refreshConfig: { |
| 59 | + refreshUrl: gmail:REFRESH_URL, |
| 60 | + refreshToken: <REFRESH_TOKEN>, |
| 61 | + clientId: <CLIENT_ID>, |
| 62 | + clientSecret: <CLIENT_SECRET> |
| 63 | + } |
| 64 | + } |
| 65 | +}; |
| 66 | +gmail:Client gmailClient = new (gmailConfig); |
| 67 | +public function main(string... args) { |
| 68 | + gmail:MessageRequest messageRequest = {}; |
| 69 | + messageRequest.recipient = "[email protected]"; |
| 70 | + messageRequest.sender = "[email protected]"; |
| 71 | + messageRequest.cc = "[email protected]"; |
| 72 | + messageRequest.subject = "Email-Subject"; |
| 73 | + messageRequest.messageBody = "Email Message Body Text"; |
| 74 | + // Set the content type of the mail as TEXT_PLAIN or TEXT_HTML. |
| 75 | + messageRequest.contentType = gmail:TEXT_PLAIN; |
| 76 | + string userId = "me"; |
| 77 | + // Send the message. |
| 78 | + var sendMessageResponse = gmailClient->sendMessage(userId, messageRequest); |
| 79 | + if (sendMessageResponse is [string, string]) { |
| 80 | + // If successful, print the message ID and thread ID. |
| 81 | + [string, string] [messageId, threadId] = sendMessageResponse; |
| 82 | + io:println("Sent Message ID: " + messageId); |
| 83 | + io:println("Sent Thread ID: " + threadId); |
| 84 | + } else { |
| 85 | + // If unsuccessful, print the error returned. |
| 86 | + io:println("Error: ", sendMessageResponse); |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
0 commit comments