What is this integration, and why should I use it?
We have enhanced the current authentication method of mail delivery for SMTP, where the messages come from customers’ domains, with the modern and secure authentication for mailbox integration solutions offered by Microsoft Exchange.
We utilize application permissions to send mail on your behalf using the designated outbox. This means your integration would continue functioning even when the user who originally authorized it is deactivated in Azure or their permissions change.
Please review the information below carefully to ensure you correctly configure the integration. We strongly recommend you engage with your Azure Administrator prior to completing any work to ensure that this is completed correctly.
Note: If you attempt the configuration while the SMTP Relay feature is enabled, it will disable it.
How to Set Up the Integration with Microsoft Exchange
Prerequisites
- You need to be an Azure Global Administrator or have another role that can grant Admin consent and has access to the mail-send APIs to use this integration.
- Consent will only be granted via one account owner in the Integrations tile for the entire org.
- You must use a version of Microsoft Exchange that supports Graph APIs. This excludes hybrid deployments.
- Your general email throughput volume should be, at most, the set Microsoft outbox limits of 10000 per day. If you will exceed this limit, you should use the SMTP relay function and other providers better suited for bulk messaging.
- We recommend limiting the application permissions to a specific Exchange Online mailbox before enabling this integration. Microsoft provides documentation, and the application ID is 1ec6ee4d-9dbf-4f55-965c-ed3dec7c901e . If you do not complete this step, you are by default granting access to all your mailboxes for the purposes of sending messages.
API Scope
| Permission Type | Permission | Purpose |
|---|---|---|
| Application | Mail.Send | Send mail on behalf of the designated mailbox |
Follow these steps to set up the Microsoft Exchange Integration
- As an Account owner, navigate to the Account Settings > Integrations page to find a new tile for this integration.
2. Click the integration tile. You will see the configuration status, if any, and a path to authorize the integration.
3. Check “Enable Microsoft Exchange,” then save to see the following menu.
4. Click the ‘Grant Consent’ button to grant Litmos consent to access your Exchange Environment to send messages.
5. You will need to accept the scope on this page. If your Azure permissions are not appropriate to grant consent, you will receive an error message indicating this.
6. After granting consent, you are returned to the integration configuration page, where you can designate a mailbox using the “Designated Mailbox” field.
What is Designated Email field and what is it used for?
This is the mailbox outbox that will be used to send Litmos system messages from. This outbox must be able to send messages to the recipients sent from Litmos and will receive all email responses if your learners reply to system messages. Litmos does not validate the mailbox, so please ensure accuracy. The message delivery will fail if the mailbox input is incorrect or otherwise not accessible to the integration.
7. Once consent has been granted and the designated mailbox field populated, you can now send a test message: enter an email address in the Test Message Recipient field and click Send Test Email. After a brief pause, you should see some message indicating that the message has sent successfully. If you are unable to proceed past this step without receiving a success message and confirming receipt of the message, ensure you disable the integration before existing this page. This will ensure that no system messages fail.
7. After a successful test, the “Last Message Timestamp” and “Last Message Status” fields will be updated. If the message has failed, you can download the API response logs to see the error message.
Once this feature is enabled, all messages that would previously have come from system@litmos.com will now come from your designated mailbox. While we receive a success message from the Microsoft Mail Send API, the message may still fail to deliver later due to another issue. The Exchange draft and outbox folder will provide the latest status of the message.
Please note the following:
- Access to the Exchange Integration depends on your subscription’s access to the “Custom SMTP” feature. If you do not have access, you will see a grayed-out tile and a popup message indicating you must contact your account manager for further information.
Troubleshooting Steps
If the test message fails
- Confirm that the mailbox designated is a valid address that can send messages.
- Confirm that your exchange environment is a cloud implementation, not a hybrid or on-premises one.
- Confirm that the application in Azure has the appropriate permission granted.
If the test message shows success but is not received by the recipient:
- Check the recipient value for any errors.
- Check the designated Exchange mailbox draft or outbox folder to verify that it is not queued to send.
- Check the inbox of the designated Exchange mailbox to confirm that the message was sent, and a deliverability error was returned.
- Check the recipient’s junk/spam folder to see if the email was distributed there
- Check recipient’s rules to make sure the email was not automatically rerouted to a different folder based on rule’s conditions