Gmail Integration Documentation for Vantage

Overview

The Gmail Integration in Vantage allows users to connect and interact with their Gmail accounts programmatically. This integration leverages the Gmail API to enable users to read emails, manage labels, access specific messages, and extract relevant data in a structured way. The primary goal of the integration is to streamline workflows involving email communication, thereby enhancing productivity and enabling powerful analytics.

Settings

The Gmail Integration requires the following settings to be configured:

1. Service ID

   • Input Type: String
   • Description: A unique identifier for the service associated with the Gmail integration. This ID is necessary for managing service-oriented tasks and applying specific configurations relevant to this integration.
   • Default Value: None (required for operation).

2. Client ID

   • Input Type: String
   • Description: The OAuth2 client ID obtained from the Google Developer Console. This ID is used to authorize the application when making calls to the Gmail API. Changing this value can affect the application's ability to access user data securely.
   • Default Value: None (required for operation).

3. Credential ID

   • Input Type: String
   • Description: A unique identifier for the user's OAuth credentials that are used to authenticate with the Gmail API. It allows the application to properly fetch and refresh access tokens. If the credential ID is not provided, certain functionalities will not work, particularly those relying on refreshed tokens.
   • Default Value: None (required for operation).

4. Access Token

   • Input Type: String
   • Description: The access token used to authenticate requests to the Gmail API. This token is generated and managed automatically by the integration, and thus does not need to be manually configured by the user. The token allows for a time-limited authentication session.
   • Default Value: None (automatically handled).

5. Token Expiry

   • Input Type: Date
   • Description: The timestamp indicating when the access token expires. The integration automatically refreshes this token before it becomes invalid, ensuring continuous access to the Gmail API.
   • Default Value: None (automatically managed).

6. Refresh Token

   • Input Type: String
   • Description: A token that allows the application to obtain a new access token without requiring a user to log in again. The refresh token is critical for maintaining long-term access to Gmail data, especially when access tokens regularly expire.
   • Default Value: None (must be obtained through OAuth2 authentication).

Important Notes on Settings:

• Google Credentials Requirement: For the authentication to function correctly, the environment must have GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET set. Failing to do so will lead to a failure in token generation and API access.
• User Authentication Required: Users must authenticate via OAuth2 to initialize and receive the necessary tokens, which will also be stored in a secure manner.

How it Works

The Gmail Integration primarily revolves around managing access tokens for interacting with the Gmail API. Here’s a step-by-step overview of how it functions:

1. Initialization: Upon creating an instance of the GmailIntegration class, it initializes configurations, including API endpoints and OAuth credentials.

2. Access Token Management:

   • The method getAccessToken retrieves a valid access token; if an existing token is expired, it will call refreshAccessToken to obtain a new one using the refresh token.
   • The integration automatically refreshes tokens when HTTP 401 errors are encountered during requests, thereby maintaining uninterrupted access.

3. API Interactions:

   • The integration provides methods like getProfile, listLabels, listMessages, and getMessage to interface with the Gmail API. Each method constructs a request to the appropriate endpoint, handling authorization transparently.
   • It also includes error handling for common issues such as invalid tokens and network errors.

4. Data Extraction and Formatting:

   • The integration provides utilities for extracting useful data from Gmail messages, such as headers, bodies, and attachments, and allows this information to be converted into a structured format that can be used for further processing or analytics.

Data Expectations

• Input Data: The integration expects the following data when making requests:

  • User's Gmail authorization through OAuth2 (client credentials).
  • Search queries, label IDs, and pagination tokens as parameters for listing messages.
  • Specific message IDs to retrieve detailed message data.

• Output Data:

  • User profile details, including email addresses and message counts.
  • List of labels associated with the user's Gmail account.
  • List of messages matching the search criteria, including snippets and metadata.

Use Cases & Examples

Use Cases

1. Email Analytics Dashboard:

   • Organizations can use this integration to analyze user email behavior by extracting patterns from emails sent and received, monitored via the metrics provided by the Gmail API.

2. Automated Email Response System:

   • Businesses can build automated systems that read incoming emails, generate concise responses based on the email's content, and can even extract attachments.

3. Message Archiving:

   • Users can automate the process of archiving important emails into a database for compliance and auditing purposes by fetching messages that match specific criteria and storing them systematically.

Example Configuration for Email Analytics Dashboard

The following example demonstrates how to configure the Gmail integration for an analytics dashboard aimed at monitoring unread emails:

{
  "serviceId": "unique-service-id-1",
  "clientId": "1234567890-abcdefg.apps.googleusercontent.com",
  "credentialId": "credential-id-1234",
  "maxResults": 50,
  "labelIds": ["INBOX", "UNREAD"], 
  "query": "is:unread after:2023/10/01"
}

• Description: This configuration allows the application to search for unread emails in the user's inbox, limited to a maximum of 50 results.
• Expected Outcome: With this setup, the user can retrieve and display analytics on unread emails received after October 1st, 2023, facilitating better email management and response strategies.

By harnessing the capabilities of the Gmail integration, users of Vantage can streamline their email workflows, improving productivity and capturing valuable insights from their communication history effectively.