Outlook Mail Integration

Overview

The Outlook Mail Integration is designed to facilitate seamless interaction with the Microsoft Graph Mail API, enabling users to manage their Outlook emails directly from the Vantage analytics platform. This integration allows users to perform various operations such as listing mail folders, retrieving messages, and sending emails programmatically, resulting in enhanced productivity and streamlined workflows.

Purpose

The primary purpose of this integration is to connect to the Microsoft Outlook mailbox via the Microsoft Graph Mail API, enabling users to perform tasks such as:

• Reading Emails: List mail folders and retrieve messages from specific folders or the entire mailbox.
• Sending Emails: Programmatically send emails to specified recipients.
• Managing Authorization: Handle access tokens to ensure secure API requests.

Settings

The Outlook Mail Integration has several essential settings that define its behavior and capabilities. The following is a detailed breakdown of each setting:

1. Encrypted Record

• Input Type: Object
• Description: Contains user credentials securely encrypted.
• Default Value: None (Must be provided during initialization).

2. Service ID

• Input Type: String
• Description: Unique identifier for the service being accessed. This is important for differentiating between multiple integrations.
• Default Value: None (Must be provided during initialization).

3. Client ID

• Input Type: String
• Description: The Client ID obtained from registering the application in Azure Active Directory. It is necessary for making authenticated requests to the Microsoft Graph API.
• Default Value: None (Must be provided during initialization).

4. Credential ID

• Input Type: String
• Description: Identifier for stored credentials that allows retrieval and updating of access tokens.
• Default Value: None (Must be provided during initialization).

5. Access Token

• Input Type: String (Internally managed)
• Description: A token used for authorizing API calls. This token refreshes periodically to ensure the integration remains functional.
• Default Value: Null (Managed internally; set after successful authentication).

6. Token Expiry

• Input Type: Date Object (Internally managed)
• Description: Keeps track of when the access token will expire, ensuring timely refresh calls.
• Default Value: Null (Managed internally; set after successful authentication).

7. Request Initialization

• Input Type: Object
• Description: Contains request-specific initialization options such as headers required for API requests.
• Default Value: Empty Object.

How It Works

The Outlook Mail Integration operates as follows:

1. Authorization Management: It manages access tokens using OAuth2 authentication. It checks for an existing token and its expiration before making any API calls. If the token is expired, it attempts to refresh the token using stored credentials.

2. API Request Handling: The integration makes requests to the Microsoft Graph Mail API by preparing URLs and initializing requests with the necessary authorization headers. It uses methods to handle API operations, ensuring secure and efficient interactions.

3. Data Handling: The integration can retrieve structured mail data, including folders and messages, which can then be utilized in the Vantage platform for analytics and reporting.

Expected Data

The integration expects the following data to be configured properly:

1. OAuth2 Credentials: These include the Client ID, Client Secret, and Refresh Token for secure access.
2. Folder and Message Structures: When calling relevant API methods, it expects formatted inputs for folders and messages as per Microsoft Graph API specifications.
3. Recipient Information: When sending an email, valid email addresses for the to, cc, and bcc fields should be provided in a proper format.

Use Cases & Examples

Use Cases

1. Automated Email Reporting: A business can automatically generate and send daily or weekly reports via email to team members, removing the manual effort of reporting.

2. Customer Support: Companies can retrieve unread customer support emails and display them in their dashboard, ensuring that team members address customer queries in a timely manner.

3. Mail Analysis: Organizations can analyze communication patterns through automated workflows that read and archive emails, extracting insights on response times or common queries.

Concrete Example

Business Use Case: Automated Reporting of Sales Leads

Configuration Example:

To send a weekly report of new sales leads to the sales team, configure the integration as follows:

{
  "serviceId": "sales_service_001",
  "clientId": "1234567890abcdef",
  "credentialId": "cred_001",
  "encryptedRecord": {
    "accessToken": "...",
    "tokenExpiry": "2023-10-30T10:00:00Z",
    "refreshToken": "..."
  }
}

Email Sending Configuration:

await outlookMailIntegration.sendMail({
    to: "sales@company.com",
    subject: "Weekly Sales Leads Report",
    body: "Attached is the report containing new sales leads from the past week.",
    contentType: "text"
});

This setup enables the integration to automate the process of sending weekly reports directly to the sales team, ensuring they stay updated on new leads with minimal manual intervention.