Submit a request

Set up Microsoft Graph API for Email Notifications

Avatar
Kepion Support
  • Updated

Introduction

Kepion allows you to send email notifications to any email provider with Microsoft's Graph API. In this article, we will walk you through setting up the API, so you can start leveraging this feature. 

 

Note: You can still send email notifications with SMTP; however, that protocol might not work with your email provider. 

 

 

Before you Start

To use the Graph API, you need the following: 

 

  • An Azure app registration. To create one, refer to the New App Registration and Configure Client Secret sections in this article. 
  • Outlook and Exchange Online (Microsoft Email Server)
  • Kepion installed within your environment

 

 

Setup Process

The setup process is three steps: 

 

SetupProcess.png

 

1. Add Mail.Send permission

Graph API's Mail.Send permission allows your app registration to send emails from mailboxes in your AD. You will add the Mail.Send permission and grant admin consent to your app registration. 

 

2. Create a mail-enabled security group

Mail-enabled security groups are used for granting access to resources (e.g., Sharepoint) and emailing notifications to group members. You will create a mail-enabled security group in Microsoft Exchange Online to define which mailboxes can send Kepion email notifications.

 

3. Create an access policy 

Access policies restrict email privileges to the mail-enabled security group defined in the previous step. 

 

 

Step 1: Add Mail.Send Permission

We first need to add the Mail.Send permission to your app registration, so it can send emails. 

 

1. Open https://portal.azure.com/.

2. Navigate to the App registrations service.

 

SearchAppRegistrations.png

 

3. Select your target App Registration to open it. 

4. Select API permissions. 

 

ApiPermissionSelect.png

 

5. Select Add a permission. 

 

AddaPermission.png

 

6. Select Microsoft Graph. 

 

SelectMicrosoftGraph.png

 

7. Select Application permissions and then Mail.Send. 

 

Mail.SendPermission.png

 

8. Select Add permissions. 

9. Select Grant admin consent for <DirectoryName>. 

 

GrantAdminConsent.png

 

Your app registration can now send emails from any mailbox within your AD.

 

Note: You can set up the security group and app policy manually by following the instructions in steps 2 and 3 OR with a script explained in the Script Setup section. 

 

 

Step 2: Create Mail-Enabled Security Group

While your app registration can now send emails, you should define which mailboxes it can use to send emails. We will define the list of mailboxes by creating a mail-enabled security group in Exchange Online.

 

Note: You will be using a functionality called App Access Policies that will soon be replaced by Roles Based Access Control. Read more about the new functionality here. 

 

1. Open https://admin.exchange.microsoft.com/.

2. Go to Recipients > Groups. 

 

SelectGroups.png

 

3. Select Mail-enabled security then Add a group. 

 

MailEnabledSecurity%2BAddaGroup.png

 

4. Select Mail-enabled security and then Next. 

 

SelectGroupType.png

 

5. Define a name and description for the group and click Next. 

 

GroupNameDesc.png

 

6. Select Assign Owners. 

 

AssignOwners.png

 

7. Select the target owners and then Add. 

 

 

8. Select Next. 

9. Add your target group members. 

 

AddMembers.png

 

Note: The selected members' mailboxes will have permission to send emails. 

 

10. Define a group email address and enable settings as desired. Click Next. 

 

EditSettings.png

 

11. Review the security group and select Create group. 

 

 

Step 3: Create Access Policy

Lastly, you need to create an access policy to limit email privileges to the mail-enabled security group defined in the previous step. The access policy can only be created using PowerShell scripts.

 

1. Open PowerShell.

 

OpenPowerShell.png

 

2. (Optional) Run the following command to install the ExchangeOnlineManagement library: 

 

Install-Module -Name ExchangeOnlineManagement

 

3. Run the following command after replacing the parameters with your information:

 

New-ApplicationAccessPolicy `
         -AppId "Aplication (Client) ID of the app registration enabled to send emails." `
         -PolicyScopeGroupId "smptp address of the created security group" `
         -AccessRight "RestrictAccess" `
         -Description "Restrict this app to members of group."  | Out-Null

 

You should now be able to send email notifications through Kepion. Ensure you configure them and edit the message if desired. 

 

 

Script Setup

Instead of manually setting up the access policy, you can run a PowerShell script. The script will: 

 

  1. Install the Exchange Online Management cmdlet from manually setting up the access policym PSGallery.
  2. Create the security group. 
  3. Assign members to it. 
  4. Create an access policy restricting the Application to use only the defined mailboxes. 

 

1. Download ps-exchange-SetPolicy.ps1 from the Attachments section.

2. Open PowerShell. 

 

OpenPowerShell.png

 

3. Change the directory to the downloaded folder with the following script: 

 

cd (Resolve-Path ~); cd Downloads

 

4. Run the following script after changing its parameters:

 

.\ps-exchange-SetPolicy.ps1
   "applicationId" `
   "securityGroupName" `
   @("emailaddress@domain.com")

 

You should now be able to send email notifications through Kepion. Ensure you configure them and edit the message if desired. 

Related articles