Use Case - Setting Up Email

How to enable and configure the Email modality


Email - The Email modality must first be enabled for your Tenant. If this is not the case, please get in touch with Customer Success to discuss availability and conditions. 


  • Contact Center Services: Note that Email modality handling is a Contact Center service Feature. The license enables the Email workflows and according Modality Service Settings
  • Users: Your License Management should now also show available Email licenses to distribute on your users. Each license enables the user to receive Email Handling service tasks.


We'll go through the details further below.


INC Icon Legend Accordion

Show Icon Legend

💡 = A hint to signal learnings, improvements or useful information in context. 🔍 = Info points out essential notes or related page in context.
☝ = Notifies you about fallacies and tricky parts that help avoid problems. 🤔 = Asks and answers common questions and troubleshooting points.
❌ = Warns you of actions with irreversible / data-destructive consequence. ✅ = Intructs you to perform a certain (prerequired) action to complete a related step.

Step 1: Tenant Setup & Licenses

Once the Email modality is available, you should be able to see configuration entries and distribute available licenses. We'll go through this step by step. 

  1. Head to your Tenant Administration > Modalities and check if the “Email Tasks” are now visible. This number informs you about the maximum concurrent limit of Email tasks. 
  2. Next, head to Tenant AdministrationLicenses and check your “Email Modality” license contingency. This number informs how many users already can handle the Email modality and draw from the license pool.
  3. You can now head to your License Management and distribute Email licenses.   
  4. Note that you can also apply these licenses directly on the General User Settings to the same effect.  
  5. Keep in mind that a Contact Center service is required to handle and distribute these Email tasks to the users. If your users are not already part of the service, head over to the Agent Service Settings and add them there.  

Step 2: Mailbox Configuration


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


Step 3: Workflow Configuration

Emails are handled in modality-specific Workflows. Those must be part of your Configuration before being visible for your services.

  1. Head to Configuration > Workflows and click “+Create new”.
  2. Select the workflow type Email and then proceed.  
  3. For starting purpose, use one of the available workflow templates and select a Organization Unit same or higher as your future Email-handling service.  
  4. You can directly Save your new workflow or make adjustments by consulting the Workflow Activities Overview.

Step 4: Apply your Service Settings

Now it's time to apply the enable the workflow, which will effectively start distribute incoming Emails.

  1. Just to be sure: Head to your General Service Settings and ensure the service uses an Contact Center license. Otherwise the next steps will not be possible.
  2. Head to the Modality Service Settings and enable Email.  
    ⮑ This will enable the “Email” section further below which allows you to apply Workflows and Mailboxes.  
  3. On the same page, scroll down and apply both your new “Email” Workflow and Service-Mailboxes.  
  4. Congratulations - once you click “Save & Apply” your service should now be able to handle Emails.

Step 5: Inform your users to get ready

🔎 All steps necessary to handle Emails are described in the Email Handling section of our knowledge base.   
✅ Ensure to make your users aware of the enabled Modality and inform them of potential Email Handling limitations and handling instructions, especially when the same users have access to the originating Mailbox.


Table of Contents