Email Security - API - Onboarding

This article contains information on completing the Mimecast Onboarding process for Email Security - API, including Account Configuration, Directory Integration, Live Mail Consent, and Mail Flow Configuration, to ensure secure email management and routing through Mimecast.

For Email Security - MX Onboarding process, see Email Security Setup Wizard - Email Security - MX - Onboarding.

If deploying Engage once Email Security - API Onboarding is complete, see Additional Configuration for Email Security - API in Engage - Rapid Deployment for Email Security - API & MX .

Overview

The Onboarding process gets you started with your Mimecast Account, by guiding you through the following sections:

• Account Configuration: Designate an Emergency Contact, select your Email Hosting Provider, and set up domains for your Mimecast Account.
• Directory Integration: Securely integrate your company's directory with Mimecast.
• Live Mail Consent: Authorize Mimecast's Azure application to scan incoming emails in real-time.
• Mail Flow Configuration: Manage your mailboxes to protect and route your organization's emails through Mimecast.

You should complete the Onboarding sections in the order given in this article.

Considerations

Email Security - API Onboarding does not currently support Google environments.

Prerequisites

• You have a Mimecast Basic Administrator role or higher, for the Mimecast Administration Console. 
• You have Microsoft Privileged Role Administrator or higher permissions.
• Designate an Emergency Contact for your Mimecast account. Mimecast will only reach out to the Emergency Contact in specific Account-related situations, e.g., spam outbreaks. 
  We recommend that these details match those of your Mimecast Account's primary administrator.

Account Configuration

For successful Onboarding, it is important to ensure that pop-up blockers are disabled prior to starting the Onboarding journey.

You can configure your Account by using the following steps:

1. Log in to the Mimecast Administration Console. You will be automatically redirected to the Onboarding wizard.
2. The Account Configuration wizard is displayed.
3. Emergency Contact:
   • Name: Enter the contact's name.
   • Email: Enter the contact's email address.
   • Mobile: Enter the contact's cell phone number.
   • Click on Next.

4. Email Hosting Provider: Select "Microsoft 365: Microsoft 365 or Microsoft Exchange Online" as your Email Hosting Environment.

5. Click on Next.

6. Deployment Option:

   • Select API-Based Email Security for Email Security - API Onboarding.
   • Click on Next.
     Read more about these deployment options at Email Security - MX versus Email Security - API.
   

Once you click on Confirm & Proceed, your deployment option cannot be changed.
Click on Confirm & Proceed, or Go Back to make changes as required.

Microsoft 365 API Dependency: Email Security - API relies on Microsoft 365 APIs for: (i) event ingestion and notifications (i.e. to trigger scanning), and (ii) enforcement actions (e.g. moving messages to Junk / Quarantine). If Microsoft APIs are unavailable, delayed or fail to execute an action, this may impact the timeliness or effectiveness of the service.

• Customer Responsibilities: To ensure optimal performance of Email Security - API, customers are responsible for: (i) maintaining valid Microsoft 365 licenses with the required permissions and API access enabled; and (ii) ensuring configuration and permissions remain accurate and up to date.
• Mimecast's Boundaries of Responsibility: Mimecast's responsibility for Customer Data begins when that data enters the Mimecast environment. Mimecast is not responsible for any delays, failures, or other outcomes attributable to Microsoft API unavailability, non-performance, or third-party service issues.

7. When prompted, confirm your selection.
   
8. Connect Your Environment (US-based customers only): Click on Connect with Microsoft 365.

For non-US customers, this step is skipped.

9. Initiate Consent Process:

   • You will be directed to a Microsoft 365 login page.
   • Sign in with Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials.
   • Review and Accept the requested permissions. See Permissions Requested by Microsoft for more information.
   • You'll see a confirmation that authorization was successful.
    
10. Set up Domains:
    • Review the domains listed, and select the domains to be added to your Mimecast Account.
    • Click on Add Domains.

• Review the Domain Status List, and click on Next or Previous, to make changes as required.

  

11. Summary:

    • Review your Account Configuration to confirm the details are correct.
    • Click on Previous if you need to go back and make any changes.
    • Click on Continue Onboarding.
    

Once completed, you will automatically proceed to Directory Integration.

Directory Integration

You can create a Directory Integration by using the following steps:

1. The Account Configuration wizard will take you directly to Create a Directory Integration.

2. Details:

   • Name: Enter a name for the integration.
   • Description: Enter a description for the integration.
   • Type: Select Integration type of Microsoft Azure - Standard.
   • Click on Next.

   

3. Settings:

   • Select Create New Connector.
   • Name: Enter a name for the Connector.
   • Description: Enter a description for the Connector.
   • Permissions: Click on Log in and sign in with Microsoft Privileged Role Administrator or higher permissions, where prompted.
   • Click on Next, or click on Previous, if you need to go back and make any changes.
   

4. Options: Set the additional integration options as required:

   • Acknowledge Disabled Accounts.
   • Filter Email Domains.
   • Include Contacts.
   • Include Guest Accounts.
   • Maximum Sync Deletions.
   • Delete Users.
     For detailed information on each option, see Directory Synchronization - Azure Active Directory Integration.
   • Click on Next, or click on Previous, if you need to go back and make any changes.

   

5. Summary: Review the integration:

   • Confirm the details for the integration are correct.
   • Click on Create Integration, or click on Previous, if you need to go back and make any changes.

   

6. You will see notifications that the synchronization request completed successfully, and the integration was created.
7. The new Directory Integration is displayed, and should show a status of Enabled.

Once completed, you will automatically proceed to Mail Flow Configuration.

Mail Flow Configuration

You can set up your Mail Flow Configuration, by using the following steps:

1. The Account Configuration wizard will take you directly to Mail Flow Configuration, where you will set up live mail scanning to monitor and protect incoming emails in real-time.

2. Live Mail Consent:

   • Click on Connect with Microsoft 365.
   • You will be directed to a Microsoft 365 login page. 
   • Sign in with Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials.
   • Review and Accept the requested permissions. See Permissions Requested by Microsoft for more information.
   • You'll see a confirmation that authorization was successful.
   
   
3. Mailbox Scope:

• Select either Groups or All Mailboxes to choose the users to include for this setup.

  Beginning with Groups will limit the scope of users and allow for a gradual rollout.

• Click on Select Groups.

  
• The Select Groups fly-over is displayed and allows you to:
  • Use the Search field to search for Group(s).
  • Click on Select All to select all Groups.
  • Remove all Groups by clicking on Clear Selection.
  • Remove Selected Groups by clicking on (x) after them.

  • Select the required Group(s).

    You must add at least one Group.

•  Click on Add Selected.

• Click on Connect.

4. Summary:

   • Review the overview of your Mail Flow Configuration.
   • Click on Go to Admin Console, or click on Manage Onboarding, if you need to go back and make any changes.
   

5. The Home page updates to show the status of Configuring Mail Flow, and to let you know when configuration is complete.
    

   

   6. Rapid learning will automatically start ingesting meta data from your users mailboxes to learn your communication patterns. This may take some time depending on the size or your organization.

The Onboarding process is now complete.

Frequently Asked Questions

Q:

Why do I need a Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials, for Onboarding?

A:

Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials, is required to grant Mimecast permission to install the Azure application with the correct scope across all mailboxes in your organization. This is a one-time requirement during setup. Once the Azure application is installed and configured, the Global Administrator credentials are not used for ongoing email scanning operations.

Permissions Requested by Microsoft

Email Security - API requires Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials, to grant consent for Mimecast to install an Azure application with specific Microsoft Graph API permissions. This is a one-time setup requirement during Onboarding. The Global Administrator credentials are not used for ongoing email scanning operations after the initial consent is granted.

The Azure application uses these permissions to scan incoming emails in real-time, quarantine threats by moving messages to hidden folders within user mailboxes, send notifications, and access shared and group mailboxes.

Required Permissions

The following table lists all Microsoft Graph API permissions required for Email Security - API live mail scanning:

Permission	Description
Directory.Read.All	Read directory data. Required for user and group lookups across all services, including Directory Synchronization.
Mail.ReadWrite	Read and write user mail. Covers basic mail operations for scanning, analyzing, and managing messages in user mailboxes.
Mail.Send	Send mail as any user. Required for sending notification emails to users about quarantined or blocked threats.
MailboxFolder.ReadWrite.All	Read and write all mailbox folders. Required to create and manage quarantine folders within user mailboxes where threats are moved.
MailboxItem.Read.All	Read all mailbox items. Covers access to messages and folders across all user mailboxes for scanning purposes.
MailboxSettings.Read	Read mailbox settings including language, locale, and timezone preferences for any user mailbox.
User-Mail.ReadWrite.All	Read and write all users' mail. Critical permission that enables access to shared mailboxes, unified group mailboxes, and cross-mailbox operations required for comprehensive email security coverage.

What These Permissions Enable

With these permissions, the Mimecast Azure application can:

1. Scan incoming emails in real-time using webhook subscriptions to Microsoft Graph API.
2. Quarantine and remediate threats by moving malicious messages to hidden folders within user mailboxes.
3. Send notification emails to users about detected and quarantined threats.
4. Access and protect shared mailboxes and Microsoft 365 group mailboxes.
5. Synchronize user and group information from Azure Active Directory.
6. Create and manage dedicated quarantine folders in user mailboxes.
    

• One-Time Consent: Microsoft Privileged Role Administrator or higher permissions, with Microsoft 365 sign-in credentials, are only required during the initial Onboarding consent process. These credentials are not stored or used for ongoing email scanning operations.
• Mailbox Storage: Quarantined messages are stored in hidden folders within user mailboxes and count against the user's mailbox storage quota. This differs from gateway-based solutions where quarantine is external.
• Webhook Subscriptions: No additional permissions are required for creating and managing webhook subscriptions. The existing Mail.ReadWrite permission covers subscription functionality.
• Shared Mailbox Coverage: The User-Mail.ReadWrite.All permission is essential for protecting shared mailboxes and Microsoft 365 group mailboxes, which are treated as user mailboxes by the Microsoft Graph API.

See Also...

• Email Security - API - Mail Flow Configuration
• Choosing Email Security Deployment Option - Email Security - MX versus Email Security - API Deployment