Applies to: SharePoint Online NITRO Workflows and Advanced Approval App
This articles has details for using an internal account to send mails from Workflow Manager and Approval App. Using an internal account results in better mail delivery as mail sent from external servers can be considered as spam by the receiving servers. This article is written taking the example of Workflow Manager, exactly same configurations are to be done for Advanced Approval App (except for Graph API).
NITRO Workflows by default sends emails using SendGrid service. This can sometimes cause mail delivery issues as SendGrid server IPs may not be trusted by receiving server. Also, mails originating outside of receiving server but with sender address of internal domain has chances of being considered a spam mail.
To avoid these issues, NITRO workflows now has the following additional options to send mails.
- Microsoft Graph API: Refer instructions from this article
- Mailbox Settings: Explained in current article
In case mail delivery by Mailbox / Graph API fails for any reason then SendGrid is used as backup. This can be configured at the site level in Workflow Manager. All workflows configured in the site will use the same settings for outgoing mails.
Note: If we need to use a shared mailbox and not the user account, we need to use Graph API method to setup internal mailbox, please refer the article for more details regarding this.
Configured mailbox requires permissions to send mails as another user or send mail on behalf of other users. Please refer this article for permission configurations.
Refer below image to configure the settings. Details of the settings are described further down:
Please refer below image for the settings. Note the text within the dialog and in the yellow boxes:
Send Mail Process Flow
Mails are sent as per below process:
- If Graph API is enabled and mail size is below 3 MB, attempt to send mail via Graph API
- If mail is not sent via Graph API (skipped or error) and Mailbox settings are enabled, attempt to send mail via Mailbox (refer example scenario below)
- If mail is not sent via Mailbox (skipped or error) and SendGrid is enabled, attempt to send mail via SendGrid
When above mailbox settings are enabled, Crow Canyon Workflow Manager component will attempt to send mails. This is done by connecting to the mailbox using Microsoft Exchange Web Services API. Workflow Manager component runs in Microsoft Azure and following IPs should be whitelisted so that mailbox can be connected for sending mails from the services running in Azure South Central US data center. Also, please ensure that multi-factor authentication (MFA) is not enabled for this mailbox account or below IPs are exempted from MFA:
[August 2019 Update] Also whitelist the following IPs:
Mailbox configuration in NITRO Workflows:
If above settings are not enabled, then mail is sent via SendGrid directly. If settings are enabled then first attempt is made to send the mail with sender as the ‘From’ address configured in the Send Mail action (‘Send As’ scenario). If this fails due to any reason like invalid sender account (firstname.lastname@example.org), then mail will be sent from the address of the mailbox configured above. And “Reply To” address will be set to the ‘From’ address (email@example.com) specified in the Send Mail action settings.
If both fail and ‘Use SendGrid’ is set to ‘Yes’ then mail is sent via the SendGrid service. Please note that if ‘Use SendGrid’ is set to ‘No’ then outgoing mails will stop working if send mail via Mailbox fails or is not enabled.
Consider following accounts for the example below:
- Mailbox account is firstname.lastname@example.org
- Email address associated with above mailbox is email@example.com (‘Sender Email’). This could be different than mailbox account in certain cases
- From address is firstname.lastname@example.org (from address configured in Send mail action in NITRO Workflows)
1. ‘Send As’
Attempt to send mail as email@example.com using the mailbox of firstname.lastname@example.org login. This requires the following:
- email@example.com login credentials configured in site workflow settings should be valid
- firstname.lastname@example.org should be a valid account
- email@example.com account should have ‘Send as’ permission on firstname.lastname@example.org account
To grant ‘Send As’ permissions, please click here. Note that we need to grant mailbox permissions to all user accounts for all the possible sender mail addresses. In short, mailbox account should have permission to send as the sender account (From address) configured in the workflow manager mailbox settings.
‘Send As’ as described above can fail for some reason, e.g. ‘Mailbox user’ not having permissions to send mail as ‘From address’ user. In this case, application will attempt to send mail with from address as mailbox email address itself (email@example.com as per example above and not firstname.lastname@example.org). In this case ‘Reply To’ address will be set as as the required sender address (email@example.com). When user replies to this email, ‘To address’ in the reply will be set to firstname.lastname@example.org.
If both the above attempts fail then mail will be sent using SendGrid service. SendGrid will be attempted if ‘Use SendGrid’ is set to ‘Yes’. Else, mail will not be sent.
Grant ‘Send As’ permission to mailbox account on one or more accounts used for sending emails
Grant mailbox permissions to a single account
Navigate to: O365 Admin Center –> Users –> Search for the required user (account that is used as sender in Workflows/Send Mail Actions, in above example, it is email@example.com) –> Mail –> Mailbox Permissions –> Grant “Send As” for firstname.lastname@example.org. Please see sample screenshots below:
Edit the Sender Account and grant “Send As” and “Send on behalf” permissions as shown below:
Note: It takes around 15-20 minutes for the mailbox permission changes to take into effect.
Grant mailbox permissions to multiple accounts simultaneously
Navigate to: O365 Admin Center –> Exchange –> Recipients –> Select the required users –> Click on More link on the right hand side panel –> Mailbox Delegation –> Grant Send As and Send On Behalf for the mailbox account configured in the NITRO Workflows App. See sample screenshots below: