Outlook

You can configure your bot to communicate with users via email. By configuring your bot to access an email account, it receives a message when a new email arrives. This enables the bot to use email as a channel for responding to user inquiries. In response to a user's email message, the bot could send an email reply.

NOTE:
  • The Outlook channel works with Office 365 only. Other email services are not currently supported.
  • This channel is available in DRUID version 9.7 and higher and only in cloud and hybrid DRUID deployments. You cannot activate the channel in DRUID on-premise deployments.
  • The Outlook channel only supports message steps. Rich content flow steps (such as hero cards or choice steps) are not supported.
NOTE: Starting with Druid version 9.12, the Outlook channel includes an email attachment antimalware scan. If an incoming email contains a corrupted or malicious file, the Flow Engine triggers the conversation using only the safe components (such as the email body and recipients). Details regarding the infected email and the malicious file names are logged in the Conversation History.

Prerequisites

Before you begin the integration process, ensure you have the following:

  • A published Druid bot.
  • A Microsoft Azure account with permissions to:
    • Register applications.
    • Grant API permissions.
  • A dedicated user email account created in the Azure Portal for the bot to use when sending and receiving emails. You can have multiple dedicated email accounts for the bot.

Configuring the Outlook channel

This section explains how to configure the Outlook channel.

Step 1. Register Microsoft Azure app

  1. Go to the Azure portal and sign in.
  2. In the left-hand navigation pane, select Azure Active Directory > App registrations.
  3. Register an app responsible for the management of the Outlook channel.
  4. Go to the app Overview page and copy the Application (client) ID and the Directory (tenant) ID. You will need them to configure the channel in the DRUID Portal.

You can now generate a client secret for your app.

Step 2. Generate client secret for your Azure app

  1. On the main menu, click Manage > Certificates & secrets.
  2. Click on the Client secrets tab.

  3. Click + New client secret.
  4. In the Description field, enter a short label (for example, Email secret).
  5. In the Expires field, choose an expiration period (for example, 6 months, 12 months, or 24 months).
  6. Click Add. The new client secret will appear in the list.
  7. Copy the client secret value immediately. Once you leave the page, the secret value will be hidden and can’t be retrieved again.

You can now configure the API permissions of your Azure app.

Step 3. Configure the API permissions of your Azure app

  1. On the main menu, click Manage > API Permissions.
  2. Click + Add a permission.
  3. In the Request API permissions panel, choose Microsoft Graph.
  4. Select Application permissions.
  5. Select the following required permissions:
    • Mail.Read
    • Mail.ReadBasic
    • Mail.ReadBasic.All
    • Mail.ReadWrite
    • Mail.Send
    • User.Read
    • User.Read.All
  6. Click Add permissions.

  7. The added permissions should now appear under Configured permissions.

    8. If your app uses Application permissions or the permissions require admin consent, you should wait until your admin grants access permissions for your organization.

Step 4. Configuring the Outlook channel in the Druid Portal

To configure the Outlook channel in the DRUID Platform, follow these steps:

  1. Log in to the Druid Portal and select your bot.
  2. Click the Channels tab.
  3. Search for 'outlook' and click the Outlook card.

    4. The channel configuration modal appears.

  4. In the Tenant Id and Client Id fields enter the values you copied from your app Overview page.
  5. In the Email address field, enter the dedicated email account created in the Azure Portal for the bot. If you want to add multiple email addresses for the bot, click the + icon and enter the email address.

    6. IMPORTANT! Do not enter your own personal email account, as every message sent to that email account will be forwarded to the bot. This can result in the bot inappropriately sending a response to a sender. For this reason, bots should only use dedicated M365 email accounts.
  6. Click the Publish button. The channel activation might take up to 1 minute.

After the channel activates, Druid automatically provisions the following [[ChatUser]] parameters in the conversation context:

  • [[ChatUser]].ChannelId = "email"
  • [[ChatUser]].UserId - Stores the email address of the sender.

The following [[Email]] metadata is available in the conversation context: Id, DateTimeSent, From, To, Cc, Subject, Body and Attachments.

Control Email Reply and Forward Behavior

You can manage how the bot replies to or forwards incoming emails using fields in the [[Email]] system entity.

NOTE: The Reply all and emails forwarding is available in Druid 9.11 and higher.

Reply Behavior

The ReplyToAll field controls whether the bot replies to all original recipients or only to the sender.

By default, the reply is sent to everyone in the original To and Cc fields.

To send the reply only to the address in the [[Email]].From field, set [[Email]].ReplyToAll = false.

Forwarding Emails

The ForwardTo field controls whether the bot forwards the incoming email instead of replying.

To forward the email, populate [[Email]].ForwardTo with one or more destination email addresses. Separate multiple addresses with a semicolon (;) and no spaces.

NOTE: When the [[Email]].ForwardTo field is populated, forwarding takes priority over the [[Email]].ReplyToAll setting. The bot forwards the message and does not generate a reply.

When the bot forwards an email:

  • The subject is prefixed with FW.

  • The forwarded message includes the original recipients, subject, and date and time at the top of the email body.

  • A system entry appears in the conversation history (Email forwarded to <recipients>).

  • Forwarding creates a new email thread. If someone replies to the forwarded email, a new Conversation ID is generated.

The [[Email]].IsForwarded field indicates whether the incoming email was originally forwarded.

Move Emails to Specific Outlook Folders

By default, all emails received by the bot are placed in the Inbox folder. To move an email message to a different Outlook folder, you must use the Microsoft Graph API via REST integrations. The process requires first obtaining an access token, then identifying the target folder, and finally executing the move operation.

NOTE: This feature is available in Druid 9.11 and higher.

The following steps outline the required REST API calls:

Step 1. Get Access Token

Use a POST request to the Microsoft Online token endpoint to acquire an access_token.

Request Detail
Method POST
URL https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
Header Content-Type: application/x-www-form-urlencoded
Body (Form Data)

client_id=<CLIENT_ID>

client_secret=<CLIENT_SECRET>

grant_type=client_credentials

scope=https://graph.microsoft.com/.default

Copy the access token.

Step 2. Get Folder List

Use a GET request to retrieve the mail folder list in the root folder for the bot mailbox, excluding hidden folders. You need the unique id property of the target folder to use as the destinationId in the move request.

Request Detail
Method GET
URL https://graph.microsoft.com/v1.0/users/<bot email address>/mailFolders
Header Authorization: Bearer token <access_token>
NOTE: You can also move emails to a hidden folder; however they are not listed by default in the response. To include hidden mail folders in the response, use the following URL in the request:

https://graph.microsoft.com/v1.0/users/<email address>/mailFolder/?includeHiddenFolders=true.

Copy the id of the folder where you want to move the email(s).

HINT: If a collection exceeds the default page size (10 items), the @odata.nextLink property is returned in the response to indicate more items are available and provide the request URL for the next page of items.

Step 3. Move Email to Folder

Use a POST request to move the message by providing the email's unique ID ([[Email]].Id) and the destination folder's ID.

Request Detail
Method POST
URL

https://graph.microsoft.com/v1.0/users/<bot email address>/messages/<MESSAGE_ID>/move.

Replace <MESSAGE_ID> with the ID of the email you want to move. This value is stored in [[Email]].Id.
Header

Authorization: Bearer token <access_token>

Content-Type: application/json
Body (Json)

{ "destinationId": "<FOLDER_ID>" }

Replace <FOLDER_ID> with the ID you copied at Step 2.

Get Extended Email Metadata to Use From Outside the Conversation

By default, the following [[Email]] metadata is available in the conversation context: Id, DateTimeSent, From, To, Cc, Subject, Body and Attachments. You can use this metadata in web views and forms (or third-party tools) to fetch, display, or manipulate the original email.

There are situations when you need to manipulate additional email metadata that is not available in the conversation context.

Typical use cases include:

  • Displaying the full message or attachments in a web view/form.
  • Populating form fields with the message content.
  • Automating message classification or tagging.
  • Downloading, modifying, or re-uploading attachments.

To retrieve all available email metadata from the Microsoft Graph API, you can use a GET request by providing the email's unique ID (stored in [[Email]].Id).

Request Detail
Method POST
URL

https://graph.microsoft.com/v1.0/users/<bot email address>/messages/<MESSAGE_ID>.

Replace <MESSAGE_ID> with the ID of the email you want. This value is stored in [[Email]].Id.
Header

Authorization: Bearer token <access_token>

Content-Type: application/json

You can use the returned JSON data in your integrations to accommodate your needs.