This article was originally published on LinkedIn.

Introduction

When you are realizing an integration platform with Azure Integration Services, one of the requirements you might come across is the need to alert a group of specific members (that have an interest in the integration) in case workflow runs fail.

Even though it is perfectly possible to configure out-of-the-box activity and metric alerts for your workflows, the resulting emails that you receive are limited and technical. The business might need additional or specific information about what is happening, and therefore these alerts will not suffice.

Fortunately, Logic Apps (Standard) have a built-in connector for Office 365 with workflow actions to send emails.

Context

Logic Apps offer some out of the box connectors to send an email:

• SendGrid. I used this connector back in the days Logic Apps consumption was new. It requires a (paid) subscription. While SendGrid being an option, in corporate environments the IT department will simply not allow to send emails through an external channel.
• Built-in SMTP Connector – Send Email. While this might be an option, it relies on the SMTP protocol, requiring a SMTP server address, port, username, and password.
• Office 365 Connector – Send email from a mailbox (V2). This connector is considered the standard approach on both Logic App consumption based and standard. 

There might be others, but in general, these are the common ones.

The problem with the Office 365 connector

The connector uses an API connection in Azure to connect to Office 365 and there isn’t a built-in connector yet for Logic Apps Standard and it has some limitations:

• This API connection only supports Office 365 accounts, which means that it is either a personal account or the account for a shared/group mailbox. Service principals or identities are not supported.
• And this means that you will will need to sign-in from the designer to create the API connection. 

• When the API connection is created manually or through automated deployment with Azure DevOps, it needs a manual consent. This consent happens from the portal and will trigger a sign-in that needs to be done on behalf of this email account that is being used.

• Furthermore, each time a redeployment happens and this API connection is recreated or updated, the consent process needs to be repeated. This is not ideal, especially not in acceptance and production environments.

With some tweaking in the deployment pipeline, you could implement that the API connection is only deployed and created once, but a first-time manual consent is still needed. 

Normally, this issue could be handled with service principals or managed identities support on the connector. But that feature is not implemented yet and therefore we need to look for alternatives. This challenge is described here.

The solution – Microsoft Graph API

Fortunately, Microsoft offers the Microsoft Graph API, which does come in handy. The Microsoft Graph API offers a gateway for services like Entra and Microsoft 365 and therefore it’s possible to send emails through this API. Even better, it can be achieved with a service principal / app registration from Entra Id. The following steps explain what needs to be done to use the API to send emails. 

Step 1: You need an app registration in Entra Id

The first requirement is that you will need an application registration in Entra Id with a client secret configured. This app registration will send emails through the Graph API and the workflow can use the registration to retrieve a valid Bearer token for the HTTP request.

For this tutorial, lets assume that this app registration’s client id will be: 11111111-2222-3333-4444-555555555555

Step 2: Give app registration the Microsoft Graph – Mail.Send permission

After creating the app registration, the next step is to give it the permission needed to send an email. This permission needs an admin consent before it is usable.

This will be the Application Permission (Mail.Send). This allows sending as any user (which is dangerous unless tightly scoped and will be explained and mitigated in step 4).

Step 3: Optional – configure firewall rules for Workflow Standard plan to have access to Microsoft Graph API

The Workflow Service Plan for Logic App Standard needs to do HTTP requests to the graph.microsoft.com API. In many environments, traffic from and to Azure workloads is strictly prohibited. So make sure that the backend subnet of you WS plan is allowed to access graph.microsoft.com on port 443 in NSG (outbound rule) and Firewalls.

Step 4: Strongly advised – Configure a mailbox for your integrations and configure Application Access Policy in Exchange Online

As mentioned in step 2, you will need to have an application-level permission on the Mail.Send in order for workflows to successfully use the functionality. Having this in place explicitly gives the app registration permission to send emails on behalf of any user. Since this is something that needs to be avoided at all costs, some measurements need to be in place.

• Create a specific mailbox (email address) for your integration layer). For this tutorial, lets assume that this logic-apps@yourdomain.com
  
• Now, open PowerShell and run the following command to connect to Exchange Online as an admin: 

Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

• Next, create a Mail enabled security group:

New-DistributionGroup -Name "MailSendAppGroup" -PrimarySmtpAddress "mailsendappgroup@yourdomain.com" 

• Then add the logic apps mailbox to that group which allows sending emails:

Add-DistributionGroupMember -Identity "MailSendAppGroup" -Member "logic-apps@yourdomain.com"

• Create an application access policy for the Logic App mailbox:

New-ApplicationAccessPolicy `
    -AppId "11111111-2222-3333-4444-555555555555" ` <-- client id of app registration
    -PolicyScopeGroupId "mailsendappgroup@yourdomain.com" `
    -AccessRight RestrictAccess `
    -Description "App can only send as logic-apps@yourdomain.com"

• Thats it! The app registration can now only send emails through logic-apps@yourdomain.com. This can be evaluated with the following PowerShell command, which will return Access granted. When the Identity is replaced with another email address, the output will be Access denied.

Test-ApplicationAccessPolicy `
    -Identity "logic-apps@yourdomain.com" `
    -AppId "11111111-2222-3333-4444-555555555555"

Step 5: Create an email template in your workflow

Now all prerequisites to email via the Microsoft Graph API has been met, and you can focus on your workflow. The first thing to do, is to have an email template or body that you want to use when sending emails from the workflow. This can be achieved with a compose action in your workflow that contains all relevant information that is needed for the email.

Step 6: Use that template to send emails of behalf of your integrations

How emails can be sent through the MS Graph API is described here. 

1) The first thing that is needed to send an email is to retrieve a valid token to call the Microsoft Graph API. 

URI:  POST https://login.microsoftonline.com/[tenantId]/oauth2/v2.0/token

Header: Content-Type: application/x-www-form-urlencoded

Body: client_id=[clientId]&client_secret=[clientSecret]&scope=https://graph.microsoft.com/.default&grant_type=client_credentials

2) After a valid bearer token is retrieved, the next step is to send the actual email with the following properties:

URI: https://graph.microsoft.com/v1.0/users/[email e.g. logic-apps@yourdomain.com]/sendMail
Header: Authorization: Bearer [token from previous step]
Body:
{
    "message": {
        "body": {
            "content": "--> The output of the compose mail template action <--",
            "contentType": "HTML"
        },
        "subject": "Oops, something bad happened with workflow ...",
        "toRecipients": [
            {
                "emailAddress": {
                    "address": "one-entry-per-recipient@yourdomain.com"
                }
            }
        ]
    },
    "saveToSentItems": "true"
}

3) The workflow sends the email, and recipient will receive it in their mailbox.

Conclusion

While sending emails with the Office 365 connector is limited in functionality, there are some other options to consider if such functionality is needed in your integrations. Not being able to use a service principal for this task, and the hassle of granting consent on the API connection each time it gets deployed, are two reasons to consider alternatives.

A good option within the Microsoft Azure ecosystem is the MS Graph API. It can be used with identities other than personal accounts, and it gives more flexibility in your deployment model. With some configuration up front, it provides a robust way for sending emails from your workflows, with little configuration.