readEmails Logic Documentation

Overview

The readEmails logic serves the purpose of fetching emails from an Outlook Mail account based on specific search criteria. This function allows users to specify filters for their email retrieval, such as the mail folder and search queries, and determines whether to include the complete body of the emails in the output. The resulting data can be used in various analytics or reporting applications, enabling users to effectively manage and analyze their email information.

Settings

1. query

• Input Type: String
• Description: This setting allows users to perform a free-text search for emails, enabling them to filter results by specific criteria. Examples include searching by subject or sender using formats like "subject:invoice" or "from:user@example.com". Adjusting this setting changes the scope of the search, leading to different email retrieval outcomes.
• Default Value: An empty string (""), which means no specific filtering is applied to the search criteria.

2. folder

• Input Type: String
• Description: This setting specifies the mail folder from which emails are to be retrieved. Users can provide standard folder names (e.g., "inbox", "sentitems", "drafts") or a folder ID. Changing this setting directs the function to search within a different folder, thus impacting which emails are fetched.
• Default Value: An empty string (""), implying that emails will be fetched from all folders unless specified.

3. maxResults

• Input Type: Numeric (integer)
• Description: This setting dictates the maximum number of emails to return in the query result, which can range from 1 to 100. The function defaults to ensuring that the number of results does not exceed this limit. Modifying this value allows users to control data volume returned, which is especially useful for performance optimization.
• Default Value: 25.

4. includeBody

• Input Type: Boolean
• Description: This setting determines whether the complete body text of the emails is included in the output. If set to true, the body text is fetched along with the email metadata; if false, only metadata is returned. Changing this setting affects the verbosity of the output data.
• Default Value: false.

How It Works

1. Integration Initialization: The function starts by building a connection instance to the Outlook Mail service using BuildConnectionInstance, passing in the context for authorization.

2. Input Processing: The function then retrieves the configured inputs or defaults for query, folder, maxResults, and includeBody.

3. Query Construction: The function formulates a listOptions object, selectively adding query and folder if they've been specified by the user.

4. Email Retrieval: The function calls the listMessages method of the Outlook Mail integration, passing along the constructed options to fetch the emails.

5. Result Processing: The function checks if any emails were retrieved. If not, it returns an empty data structure with metadata including the query and folder details. If emails are found, it converts the results into a flat array of simplified row data using OutlookMailIntegration.messageToRow, optionally including the body text based on the setting provided.

6. Error Handling: Any errors encountered during the connection or fetching process are logged and returned in the response.

Expected Data

The readEmails logic expects:

• Input Data:

  • query: Optional search criteria as a string.
  • folder: Optional folder to search within as a string.
  • maxResults: Optional maximum results to retrieve as an integer (1-100).
  • includeBody: Optional flag to include the email body as a boolean.

• Output Data:

  • Returns a structured object with:
    • output1:
      • data: An array of objects containing email details, including:
        • id
        • subject
        • from
        • to
        • date
        • snippet
        • body (optional based on includeBody)
      • metadata: An object containing:
        • query
        • folder
        • totalResults: Count of emails returned.

Use Cases & Examples

Use Case 1: Automated Invoice Processing

In a business environment where invoices are frequently sent via email, the readEmails logic can be deployed to automatically fetch emails matching invoice subjects from a designated invoices folder.

Use Case 2: Customer Service Email Monitoring

Customer service teams can utilize this logic to retrieve emails from a shared inbox folder, tracking customer inquiries by filtering based on specific keywords in their emails.

Concrete Example

Scenario: A users wants to retrieve the latest 50 emails from their "inbox" that contain the subject "Invoice" and include the full body of those emails.

{
  "inputs": {
    "query": "subject:Invoice",
    "folder": "inbox",
    "maxResults": 50,
    "includeBody": true
  },
  "config": {}
}

Explanation:

• The user is searching for emails specifically related to invoices within their inbox.
• By setting maxResults to 50, the user ensures they get a substantial number of emails for analysis.
• Setting includeBody to true allows the user to view the complete content of each email for detailed inspection.

Upon execution, the function would return the matching emails, allowing the user to review or process the invoice information as needed.