Add an email trigger

Starts a bot when a new email message is received from the predefined email service.

Connect the Control Room to one of the email services on your system and trigger the bot when you receive a new email.

For email automation, you can use OAuth 2.0 to authenticate with the email server. To register your application with the Microsoft identity platform, see Using Connect action in Email package

Procedure

  1. On the left pane, click Automation.
    A list of available bots and forms is displayed.
  2. Click Create new > Bot.
  3. Enter a name for the bot.
    All the bots are stored under the \Bots folder. (Optional) Click Browse to change the folder.
  4. Click Create & edit.
  5. In the bot builder page, click Triggers > Email trigger.
  6. Drag Email into Drag a trigger here.
  7. Use the Email trigger pane on the right to choose one of the following server types as the trigger for your incoming emails:
    Server typeSteps
    Microsoft Outlook Click Outlook.

    Microsoft Outlook is set as the email service and the bot is triggered when you receive a new email.
    Email server Click Email server.
    1. Enter the email service Host information.

      For example, if you are using Office365 as your email service, enter Outlook.office365.com.

    2. Select IMAP or POP3.
      IMAP and POP3 are protocols used to connect to the mail server that enables you to read your emails through an email client.
      Note: The POP3 protocol has a known limitation where any new calender invite can also trigger the bot.
    3. Use secure connection (SSL/TLS): Select this option if you want to use a secure connection with the mail server.
    4. Enter the configured port number for your email server.
    5. Select one of the following user authentication methods to sign in to the email server:
      • Basic
      • Client credentials
        • Specify the unique client and tenant IDs generated when you registered the application in the Microsoft Azure portal.
        • Specify the username you want to use to access the mail server.
        • Specify the client secret that you generated for your app in the app registration portal.
          For Client ID, Tenant ID, Username and Client Secret fields, choose from Credential or Insecure string tab:
          • Credential: Use a value available in the credential vault.
          • Insecure string: Manually enter a value.
          Note: Client Credentials flow does not support Gmail.
      • Control Room managed

        To use Control Room managed OAuth2 mode of authentication to automate Gmail, you must configure the OAuth connection in the Control Room. See Create OAuth connection.

        Update the information in the following fields:

        • Connection: Click the Pick button to select a connection type.
        • Select Custom in the Provider type field.

        • Select the connection name that you set up in the Control Room for Google Workspace apps.

        • Use the Token type field to select one of the following options:

          For information about the Google Workspace application access and refresh tokens, see Configure enterprise applications

          • Shared: Select this option when the OAuth2 access token is shared for all users running the automation.
            Note: This option requires the Control Room administrator or any user (with Manage connections and View connections options enabled for the OAUTH CONNECTIONS) to set up an OAuth connection in the Control Room. Save the login credentials one time to generate a shared access token that can be used by all users running the automation.
          • User-specific: Select this option when the OAuth2 access token is specific to each user running the automation.
            Note: This option requires the Control Room administrator or any user (with Manage connections and View connections options enabled for the OAUTH CONNECTIONS) to set up an OAuth connection in the Control Room. Ensure you do not save the login credentials so that each user running the automation can provide their login credentials and generate an access token that can only be used by that specific user.
          • Click Confirm.
        Note: When you use User-specific option, you must log in to your Google account to authenticate and generate a user-specific token. Perform the following steps to use this option:
        1. In the Control Room, navigate to your profile My settings > OAuth connections.
        2. Click Login to authenticate.
        3. Sign in to your Google account and select Continue.
        4. Verify the services you have access to and Click Continue.

          If the connection is succeeded, it will display the status as Active.

      Note: The Email in folder does not support sub-folders when you set the protocol as POP3 for Email Server,
    EWS server Click EWS server.
    1. From the Microsoft Exchange Version drop-down menu, select your current version.

      For example, if you are using Microsoft Exchange Service Pack 2, select Exchange2010_SP2 as your email service.

    2. Enter the domain name, for example, smtp.office365.com
    3. Select one of the following user authentication methods to sign in to the email server:
      • Basic
      • OAuth 2.0 - Client credentials
        • Specify the unique client and tenant IDs generated when you registered the application in the Microsoft Azure portal.
        • Specify the username you want to use to access the mail server.
        • Specify the client secret that you generated for your app in the app registration portal.
          For Client ID, Tenant ID, Username and Client Secret fields, choose from Credential or Insecure string tab:
          • Credential: Use a value available in the credential vault.
          • Insecure string: Manually enter a value.
          Note: There is no shared mailbox support for Microsoft Outlook but as a workaround, you can use the EWS server credentials flow with a shared email as a username string.
  8. Optional: Use the Check every drop-down menu available under all the server types to set the trigger interval.

    The trigger interval for the bot is set to 120 seconds by default.

    Note: The trigger interval that you have configured using the Check every drop-down menu does not depend on the number of emails received during the scheduled interval.

    For example, if you have configured Check every to 1 second, the task is triggered only one time even if you receive three different emails at same time. The run time filter of polling is updated to the sent date time of the email for which the last trigger was run.

  9. Optional: Use Select Conditions to specify an email event for the selected server type.
    Consider a scenario where you select Outlook and want to trigger a bot when you receive an email from a specific sender. In Select Conditions, select the Email from check box and specify the sender's email address.
    When you select the Email subject contains check box, the email trigger is executed depending on the following subject conditions:
    • When the subject line is provided within double quotation marks (""), for example, "ABC spreadsheet", the trigger is executed only when the email subject has an exact match for the string provided within quotation marks.
    • When multiple subject lines are separated by semicolons, for example, ABC spreadsheet; ABC project logs, the trigger is executed when the email subject matches any of the subject lines mentioned.
  10. Optional: To create a variable, in the Assigned to > Record tab, click Select variable icon.

    You can use this variable to retrieve various details about the email that triggered the bot, such as sender, recipient, subject, email content, date, action information, email server host, and port data.

  11. Click Apply.
  12. Click Run > Run with triggers.
Microsoft Outlook, Email server, or EWS server is set as the trigger to start the bot for new emails.
Note: When you run an email trigger, the emailTo key returns a list of To addresses. To convert the list of To addresses into a string, use the Assign action from the List package and then use the Join items action from the List package, with the comma as a delimiter to separate the addresses.