readEmail Documentation

Overview

The readEmail node is a defined logic component within the Vantage analytics and data platform, specifically for retrieving a single email from an Outlook mailbox using its unique message ID. This logic encapsulates the integration with Outlook Mail API, allowing users to programmatically access specific emails' content, such as the subject, sender, recipient, date, and body of the email.

Purpose

The primary purpose of the readEmail logic is to fetch and return the details of a single email message from an Outlook account. This component is essential for applications that require email content retrieval for analysis, monitoring, or response automation.

Settings

1. messageId

• Input Type: String
• Description: This setting is crucial as it specifies the unique identifier for the email message that needs to be fetched. Without it, the logic cannot function as it does not know which email to retrieve.
• Impact of Changes: If the messageId is set incorrectly or is not specified, the logic will fail and return an error. A valid message ID is required to initiate the request to the Outlook API successfully.
• Default Value: None. This is a required field and must be provided either as part of the inputs or configuration phase.

How It Works

The readEmail node operates asynchronously and follows these steps:

1. Build Connection Instance: Upon invoking the function, it first constructs a connection instance to the Outlook Mail integration using BuildConnectionInstance.

2. Retrieve messageId: It attempts to extract the messageId from the provided inputs or the configuration settings.

3. Error Handling: If the messageId is not provided (either from inputs or config), it returns an error indicating that the message ID is necessary to proceed.

4. Fetch Email: Once a valid messageId is available, the logic calls the Outlook Mail integration's method getMessage to retrieve the email.

5. Transform Data: The message is transformed into a structured format via the OutlookMailIntegration.messageToRow method, which creates a normalized data row.

6. Output: Finally, it returns an object containing the email details, wrapped in another object under the key output1. This object also includes metadata that lists the message ID and conversation ID.

Expected Data

The readEmail node expects the following data:

• Input:

  • A required string representing the messageId of the email to be fetched.

• Output:

  • An object structured as follows:
    jsonCopy

    {
        "output1": {
            "data": [
                {
                    "id": "email_id",
                    "subject": "email_subject",
                    "from": "sender@example.com",
                    "to": "recipient@example.com",
                    "date": "email_date",
                    "body": "email_body"
                }
            ],
            "metadata": {
                "messageId": "fetched_message_id",
                "conversationId": "optional_conversation_id"
            }
        }
    }

• Error Handling:

  • If there are issues, like a missing messageId or problems communicating with the Outlook API, an error message will be returned instead of the email data.

Use Cases & Examples

Use Case 1: Automated Email Analysis

A business could use the readEmail node in a data pipeline to fetch customer emails for sentiment analysis, thus helping customer service teams respond effectively to customer queries.

Use Case 2: Email Archive Retrieval

An application designed for archiving communications can leverage this node to extract specific emails from an account based on user requests or audit requirements.

Use Case 3: Email Notification Systems

This logic can be employed in a notification system that alerts users by extracting relevant email details when specific conditions or events occur.

Example Configuration

Scenario: Fetch a specific email to analyze customer feedback.

Configuration:

{
    "inputs": {
        "messageId": "abc123xyz"
    },
    "config": {}
}

In this configuration, the input messageId is set to a specific ID (abc123xyz). When this configuration is executed, the readEmail component will make a request to retrieve the associated email, returning its details if successful, or an error message if not.

Billing Impacts

While using the readEmail logic, billing impacts may arise based on the number of API calls made to the Outlook service. Each invocation that successfully fetches an email counts as an API call, potentially affecting costs if the usage exceeds the allocated billable quota. Users are encouraged to monitor their API usage to manage costs effectively.