Sending emails via Azure Communication Services SMTP

There are many situations where it is helpful to get a message from your active pipelines. These may include logs, summaries of successful completion or possibly even an integration with downstream systems. 

CloverDX provides a component EmailSender to cover this need. It uses the standard Simple Mail Transfer Protocol (SMTP) and is capable of not just sending messages themselves but can also transfer multiple attachments. But first it needs to be configured to do so. 

Where previously one would just configure SMTP server locally, these days cloud-based options are more often used. For this article, we will use Azure Communication Services (ACS) as the authorization server of choice to make our CloverDX graph able to send emails via SMTP. ACS offer tools for adding communication features like voice, video, chat, SMS and email to applications. They are part of Azure ecosystem and can be managed via Azure Portal.

This article will first delve into which emailing permissions is Azure offering before providing a step-by-step guide to configuring both Azure and CloverDX side of sending emails. In some future article we may also have a closer look at the reading aspect. 

Types of ACS permissions 

There are two main categories of permissions offered by Azure Communication Services for two distinct types of apps: 

• delegated 
• application

Some APIs offered by ACS support both types of permissions, some only either. 

Delegated 

Delegated permissions are used by user-dependent apps. They act on behalf of a user within specified scopes. Email clients or social media schedulers fall into this category. 

Their authorization follows OAuth 2.0 authorization code flow: user uses authorization server to allow application to utilize part of their access. It is so-called “3-legged OAuth” as there are three parties involved: user, application and server. Admin consent is often not needed here. 

Available delegated permissions for emailing

• IMAP.AccessAsUser.All – reading  
• SMTP.Send – sending 

Application 

On the other hand, application permissions are used by user-independent apps. They act independently within their specified app roles. Imagine automatic email archivers running in the background, company-wide notification systems or scripts used by IT Ops for bulk editing of user permissions. 

 Their authorization follows OAuth 2.0 client credentials flow: application authenticates with authorization server using its own credentials. This is thus “2-legged OAuth” as there are only two parties involved: application and server. Due to their much bigger powers all application permissions require admin consent. 

 Note what OAuth calls “client” is what Azure calls “application”. 

Available application permissions for emailing: 

• Mail.Read – reading 
• Mail.ReadBasic.All – reading (not body and attachments) 
• Mail.ReadWrite – reading, creating, updating, deleting 
• Mail.Send – sending 

Summary 

Configuration 

As of CloverDX v7.0, only 3-legged OAuth is currently supported natively by emailing components so only delegated permissions can be used there. Application permissions could still be used, though the process of sending messages cannot leverage the convenient EmailSender component.  

Let’s now get to the setup of sending emails via delegated permissions in Azure and in CloverDX. 

Configuration in Azure Portal 

1. In your web browser, navigate to https://portal.azure.com.  
2. Select the “App registrations” option in the “Azure Service” section and click on “New Registration”.  
3. Choose a name and select the “Web” option in the “Redirect URI” drop down. The value for the “Web” option would be your CloverDX Server URL followed by “/oauth2”, so for instance: http://localhost:8083/clover/oauth2  
   
4. When the app is created, navigate to “API Permissions” and click on “Add permission”. Go on to choose “Microsoft Graph” and then, “Delegated permissions”.   
5. In the “Select permissions” search, type “SMTP”. The search will bring up a single “SMTP” record that after expanding shows a single record called “SMTP.Send Send emails from mailboxes using SMTP AUTH.” By selecting this checkbox, you will give the app a permission to send emails. Select the checkbox and save the changes by clicking on the “Add permissions” button.  
   
6. In the “Certificates & secrets” section, click on “New Client Secret”. Fill in description and expiration of your choice and click “Add”. Copy the content of the “Value” column. Note: Make sure to do this before switching to a different section because the secret value cannot be retrieved afterwards. 

Configuration in CloverDX 

1. Make sure you’re working on Server Project in CloverDX Designer.  
2. In the “Outline” pane, right-click “Connections”, then select “Connections” > “Create OAuth2 connection”.   
3. OAuth2 connections are always externalized in CloverDX so you would need to save it in the “conn” directory of your sandbox with an arbitrary name. Click “Next”.  
4. Change the “Provider” from “Generic” to “Azure”.  
5. Paste the previously copied Client Secret value from Azure into the “Client Secret” field in CloverDX.  
6. Fill in the scopes that you previously selected during the app registration in Azure. Make sure to prefix them with “https://outlook.office.com/”. Multiple scopes need to be separated by a space character. For example, if you selected both IMAP and SMTP permissions so that  your app can both read and send emails you would populate the “Scopes” with this value:   
   “https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send” 
7. To fill in the remaining items from the “Basic” tab, navigate to the “Overview” section in the Azure Portal and go on to:  
   1. Copy the “Application (client) ID” value from Azure and paste it into the “Client ID” field in the Designer.  
   2. Copy the “Directory (tenant) ID” value from Azure and paste it into the “Tenant ID” field in the Designer.
8. As a confirmation, navigate to the “Advanced” tab (in the Edit OAuth2 Connection screen) and double-check that the “Redirect URL” matches the “Redirect URI” configured in Azure (Authentication > Platform Configurations > Web). If not, adjust the “Redirect URI” in Azure to match the “Redirect URL” in CloverDX.
9. Click on “Authorize”. This will bring up a login screen so pick your account and accept the requested permissions. 
10. Your connection will be authorized. 
11. Add EmailSender component to your graph. Note it sends an email for each incoming record so in case you want to obtain just one email (e.g  a notification with the count of processed rows after a successful run) add also Aggregate before it.
12. Consider also adding Map component to the graph. While you can setup the email directly inside EmailSender, using separate component to prepare its parts (subject, from, to...) would make your graph more organized. It will also allow you to review the setup by inspecting the edge from Map to EmailSender.
13. Set Aggregate to count all processed rows. 
14. Set Map to prepare the message. Subject, from, to and body are required parts of email. As you are using delegated permissions, put your own email address in from field. You can also add a name of file to be sent as an attachment here. 
15. Next, open EmailSender component and set its Message property to use the prepared email parts.
16. There are several ways to setup attachments: it can either be a local file or be included directly in input data. Here we obtain the path to the sent file via attachment field prepared in Map component.
17. Finally, configure EmailSender to utilize the newly created OAuth2 connection.
18. Voila, your graph should now be able to send email notifications. 
19. For more details, please consult our docs for EmailSender or Delegated OAuth2 connections.