Configuring Email Sending/Receiving with Microsoft Graph

This page describes the necessary steps to configure email sending and receiving using Microsoft Graph and an user with an Exchange Online maibox.

Pre-Requisites

1. Ensure you comply with the pre-requisites at Pre-Requisites (Virtual Networks) and Pre-Requisites (in that order) and that you have sufficient permissions to create new App Registrations in Microsoft Entra ID.

2. Ensure you comply with these additional pre-requisites:

   1. Access to an account with Global Admin or Exchange Administrator permissions

   2. Access to an available Exchange Online license

   3. Have the ExchangeOnlineManagement PowerShell module installed in your machine or on Azure Cloud Shell

Creating mailbox and assigning Exchange Online license

1. If you have an existing mailbox you wish to use, you can skip this step. Otherwise, to create a new maibox:

   1. In Azure Portal, navigate to Microsoft Entra ID

   2. Click Add -> User -> Create New User in the top left corner

   3. Create a new user with the desired email address (e.g., [email protected]).

   4. Go back to Microsoft Entra ID and open the Licenses -> Assignments menu

   5. Verify if the user has an assigned license (for example, Microsoft 365 E3).

      1. If not, assign a license that includes Exchange Online.

      2. The mailbox will be automatically created after assigning a license.

Create App Registration

1. In the top-left corner of the Microsoft Entra ID page, click "Add -> App registration".

2. In the next page, choose a name for your app. We recommend a memorable and unique name so you can easily reference this registration in the future.

3. Choose which accounts can access your registration/app. We recommend setting "Accounts in this organizational directory only" (usually the default option), as this limits logins to users in your organization.

4. Your final registration will look something like this:

   

   Hit "Register" once done.

5. Navigate to API Permissions -> Add a permission -> Microsoft Graph -> Application Permissions

6. Add the following permissions:

   1. Mail.ReadWrite: SmartDocumentor requires this permission to read your mailbox, providing the functionality to upload files via Email

   2. Mail.Send: SmartDocumentor requires this permission to send emails from your mailbox, providing the functionality to send notifications and email confirmations

7. Check "Grant Admin Consent", which requires admin privileges. This is necessary as the permissions requested require privileged access to the mailbox.

8. In the registrations' page, head to "Certificates and Secrets" and click "New client secret". Name your secret and assign it a suitable expiration according to your compliance and security requirements.

9. Once created, copy the Value of the created secret to a secure temporary place. You won't be able to view this value after you leave this page.

10. Navigate to the "Overview" tab of the app registration, and copy the Application (client) ID and Tenant ID values.

Restricting mailbox access

This step is recommend otherwise SmartDocumentor will have unrestricted access to all mailboxes in your organization.

1. Open PowerShell and install the ExchangeOnlineManament module

Install-Module ExchangeOnlineManagement -Scope CurrentUser

1. Connect to Exchange Online with your admin email

Connect-ExchangeOnline -UserPrincipalName [email protected]

1. Verify the mailbox you created before exists

Get-Mailbox -Identity [email protected]

If this command returns the details of the mailbox, it is correctly created.

1. Create the Application Access Policy to restrict your newly created App Registration to only use the mailbox you specified

New-ApplicationAccessPolicy `
-AppId YOUR_APP_REGISTRATION_CLIENT_ID`
-PolicyScopeGroupId [email protected] `
-AccessRight RestrictAccess `
-Description "Restrict YOUR_APP_REGISTRATION_CLIENT_ID access only to [email protected]" `
-Name "AppPolicy_MSGraphMailUsage"

1. Test the created policy:

Test-ApplicationAccessPolicy -AppId YOUR_APP_REGISTRATION_CLIENT_ID -Identity [email protected]

If the result is AccessCheckResult : AccessAllowed then the configuration is correct - the app registration can only access the specified mailbox.

1. Optionally, you can manage access policies

# List existing policies
Get-ApplicationAccessPolicy

# Remove a policy
Remove-ApplicationAccessPolicy -Identity "AppPolicy_MSGraphMailUsage"

Configuring email in application settings

1. With the app registration's values copied, navigate to the resource group where you deployed SmartDocumentor and find the Key Vault resource with the name kv-app-config-xxxxxx , where the last 6 characters are unique to your deployment.

   1. Click the "Secrets" tab under "Objects" on the left.

   2. Add the following six secrets with the following parameters:

      1. Name: EmailWorkerConfiguration--Active , with value true.

      2. Name: EmailWorkerConfiguration--ClientId , with the value set to the Client ID you copied in the previous step.

      3. Name: EmailWorkerConfiguration--ClientSecret , with the value set to the Secret Value you copied in the previous step.

      4. Name: EmailWorkerConfiguration--TenantId , with the value set to the Tenant ID Value you copied in the previous step.

      5. Name: EmailWorkerConfiguration--FromEmail , with the email that will be set on the "From" field whenever SmartDocumentor sends an email with your configuration. Usually the same as your mailbox email configured previously.

      6. Name: EmailWorkerConfiguration--UserId , with the same email as your configured mailbox.

Restarting the application

1. Navigate to the smart-documentor Container App and click the "Containers" tab under "Application". In this page, click "Save as a new revision" and wait until the revision is applied. If "Save as a new revision" is not available, simply disable and re-enable the container in the "Overview" tab.

2. After restarting, the following changes will be in effect:

   1. Confirmation emails are now sent to all accounts when registering in the platform

   2. It is now possible to import files via email (Inbox -> Import -> Email for more information)

   3. Various email notifications are now enabled (Expiring Secrets, Approval notifications, and more)

Summary

Step	Expected Result
Creating mailbox and assigning Exchange Online license	Active and licensed mailbox
Create App Registration	App Registration configured
Restricting mailbox access	App registration can only access specified mailbox
Configuring email in application settings	Email configured in application settings Key Vault
Restarting the application	Email receiving and sending features enabled in the application

Additional Notes

• Only one mailbox can be directly assigned to a restricted access policy.

• To allow access to multiple mailboxes, create a group and use its ID as PolicyScopeGroupId.

• Remember to renew the Client Secret before it expires (default 6–12 months).