Exchange Mailbox to receive and process EMails in Nimbus

Email In order to use the Email modality you need to set up an Microsoft Exchange Mailbox with unique UPN on your tenant. Nimbus will subscribe to this mailbox, listening for new incoming mails to distribute as described in Email Handling.

Mailbox creation in Nimbus

To create a new Mailbox in Nimbus, head to the Admin Portal > Configuration > Service > Mailboxes. In here you can create a new mailbox with the following settings:

Area Description

Name of your Mailbox, as it will appear in lists and configuration dialogues.

💡Does not need to match with your Exchange Mailbox name.

Organization Unit The Organization Unit under which this Mailbox will be visible for selection in services Modality Service Settings and in respective Email Workflows.
Mailbox UPN

✅You need to create an Exchange Mailbox UPN to put in here. → See Prerequirements above. Requires a valid and unique UPN format to work. 


💡Uniqueness of the mailbox will be validated across the tenant. 
💡The Mailbox UPN value is editable only if selected Mailbox is not already assigned to any Service via Modality Service Settings


Managing Mailbox access for Nimbus

Required Nimbus App Permissions for reading Mailboxes are requested when the first service that applies a mailbox in its Modality Service Settings and thus starts an Exchange inbox subscription. Afterwards the permissions are already granted for all further services. While convenient for scaling large amounts of mailboxes quickly, this may not be desiderable from a security point of view

Once a Tenant Admin has run the Provisioning PowerShell script, permissions are by default granted for all mailboxes on your tenant.


Learn here how to apply access restriction policies to (select) mailboxes

INC Mailbox Access Restriction

Why enforce mailbox access policies?

When you run the Provisioning via Microsoft PowerShell , the script tries to get the consent for 2 additional Mail-related Nimbus App Permissions on the Luware Nimbus Application:


☝This grants Nimbus access on ALL mailboxes (currently available) which may be desirable if you want to still set-up and test the feature. After that however you may want to restrict the access only to selected Mailboxes by creating an Application Access Policy

🔎 You can find further information on this Microsoft Website.

✅ Detail steps to follow will be described in the following.


Create a MailUniversalSecurity Group

💡Tip: A MailUniversalSecurityGroup makes managing additional Mailboxes easier in future. In the following example we're using a group for the access policy. 


As a Exchange Admin: 

  1. Go to your Exchange Admin Center. 
  2. Go to the Recipients section and select Groups. Click on Add a new group.
  3. On the Choose group type page select “Mail-enabled security”
  4. Fill in Name (e.g "Luware Nimbus Service Mailboxes) and add a description of your choice.
  5. Select the Group Owners.
  6. Select the Mailboxes, which should be part of this restriction.
  7. Select an Email address and select the settings you would like to enforce.

Connect via PowerShell to Exchange Online

✅To connect to Exchange Online using PowerShell you need to install the module “Exchange Online Management”.  If the module is already installed, you can typically skip this step and run Connect-ExchangeOnline (Step 4) without manually loading the module first.

  1. Open Powershell as Admin mode.
  2. You will have to run the Install and Import commandlet
    install-module ExchangeOnlineManagement
  3. As the next step, you have to connect with Exchange Online.
  4. Enter: Connect-ExchangeOnline -UserPrincipalName <UPN>
    ☝ Replace “<UPN>” by the UPN of an Exchange administrator.
    ⮑ You are now connected to Exchange Online  

ApplicationAccessPolicy Restriction Steps

In order to restrict the Luware Nimbus App access only to selected Mailboxes perform the following steps:

  1. Ensure you are connected to Exchange Online via PowerShell.
  2. Identify a Mail-enabled security group to restrict the app's access to.
  3. Depending on the Cluster you test this on, retrieve the Nimbus App ID from the reference below.

    Nimbus ACS / APP ID

    Click to show…

    INC Nimbus ACS App ID

    Cluster Unique ID
    Innovator Cluster
    Luware Nimbus Innovator APP ID 953900f0-0e95-4116-80bf-de894301fa29
    Luware Nimbus Innovator ACS ID fa5a344d-cfe3-4765-b478-dc6551f153e2
    Production Cluster
    Luware Nimbus Production APP ID af85ba37-5817-43d6-82e7-09004f08664e
    Luware Nimbus Production ACS ID 0ec02475-4b29-4cb5-8338-aa5623d301a2
    Nimbus ACS / APP IDs
  4. Run New-ApplicationAccessPolicy with the following parameters:

The AccessRight parameter specifies the restriction type that you want to assign in the application access policy. Valid values are:

  • RestrictAccess: Allows the associated app to only access data that's associated with mailboxes specified by the PolicyScopeGroupID parameter.
  • DenyAccess: Allows the associated app to only access data that's not associated with mailboxes specified by the PolicyScopeGroupID parameter.

The Identity parameter specifies the GUID of the apps to include in the policy. To find the GUID value of an app, run the command:

Get-App | Format-Table -Auto DisplayName,AppId

The PolicyScopeGroupID parameter specifies the recipient to define in the policy. 

Valid recipient types are security principals in Exchange Online (users or groups that can have permissions assigned to them). 


For example:

  • Mailboxes with associated user accounts (UserMailbox)
  • Mail users, also known as mail-enabled users (MailUser)
  • Mail-enabled security groups (MailUniversalSecurityGroup)

💡Tip: We recommend the MailUniversalSecurityGroup option in order to add additional Mailboxes in future. See above how to create this group, if you haven't done so already.

New-ApplicationAccessPolicy parameters

Full command:

Once your parameters are set, run the New-ApplicationAccessPolicy as follows:

New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId "<Luware Nimbus AppId>" -PolicyScopeGroupId “<your MailUniversalSecurityGroup>” -Description "<your Description>"
Example of the “New-ApplicationAccessPolicy” script run

 You can test your ApplicationAccessPolicy with the following commandlet:

test-ApplicationAccessPolicy -AppID <NimbusAppID>
Testing for an existing ApplicationAccessPolicy

Note: Policy Limitation

☝ You can only create a limited number of policies in your organization, based on a fixed amount of space. If your organization runs out of space for these policies, you'll see the error: "The total size of App Access Policies exceeded the limit."  


Starting Mailbox Subscription

Once assigned to a service (when applying in Modality Service Settings), Nimbus immediately subscribes to changes in the mailbox in the following way:

  • Will create any missing folders (Inbox, Handled, WF Ended, Failed) which Nimbus will use for task-sorting.
  • Will start checking for incoming new mails in Folder “Inbox” , only considering mails after the subscription was enabled.
  • Will not start service sessions for automatic replies (these can be detected). Such ⮑ mails will be moved to a “Failed” folder.
  • Will not detect automatic distribution Emails (like weekly summaries sent by Microsoft) or advertisements.

Cancelling a Mailbox Subscription

A subscription to a mailbox gets cancelled under the following conditions: 

  • The mailbox is unassigned from the service via Modality Service Settings.
  • The related service is suspended/deleted.
  • The entire tenant is suspended (as seen on the License Management tab).
  • When the mailbox UPN changes on Microsoft side
    ⮑ Nimbus will lose the subscription and the service cannot accept Email tasks anymore. 
  • Any “in progress”  Email tasks prior to cancellation will be completed.

Restoring a Mailbox Subscription

Whenever the the “Modalities” tab on a service is re-opened Nimbus will try to resubscribe. An error message below the mailbox field will inform when a problem persists, e.g. on a changed or missing address a warning message would be shown. 

Example warning message below the “Mailbox” pulldown

While an active subscription is already ongoing, Nimbus will attempt to resume from any error, picking up Emails for the task queue where left of. 

Manually removing or changing subscriptions

☝ Nimbus is not using a polling subscription/change notifications functionality, meaning that Nimbus will process only those Emails, that appeared in Inbox folder after the mailbox was (re)assigned to a service.

☝ When a mailbox is removed or otherwise re-applied the same service, it will treated the same as a newly subscribed mailbox. Existing mails will not be processed retroactively.

☝The same rule applies for a tenant resumed from suspension. Any mails that were received outside of a subscription period will not be processed retroactively.


Follow-up steps


Table of Contents