Setting up Graph API connection for your Microsoft Office 365 mailbox in ShopCtrl

This article describes the process of setting up your Microsoft Office 365 mailbox in ShopCtrl based on the OAuth authorization flow using Microsoft Graph API.

Below are the four steps you need to accomplish to set up a Microsoft Office 365 mailbox in your ShopCtrl environment.

Step 1. Create and configure an API application for ShopCtrl

1. Sign in to the Microsoft Azure Active Directory administration console as an admin.

2. In the Azure Active Directory admin center, go to the Enterprise applications > All applications and click New application.
3. On the Browse Azure AD Gallery page click Create your own application.

4. In the What's the name of your app field, enter any name you want to use to find the added app in the list of Active Directory apps.
5. Select Register an application to integrate with Azure AD (App you're developing).
6. Click Create. The added program will appear in the workspace in the Enterprise applications section. The Register an application window will open.

7. On the Supported account types section select: Accounts in this organizational directory only (Single tenant).
8. On the Redirect URI select Web and enter your ShopCtrl environment URL with a path to the mail authorization: https://{HOST}/Mail/Microsoft365/Auth.aspx.
9. Click Register.

Step 2. Grant permissions to the ShopCtrl application

To complete application registration, we need to grant new app API permissions to retrieve mail and send mail.

To add minimal required API permissions to the new app:

1. Go back to Enterprise applications > All applications.
2. Click on the app you just created. The application details will open.
3. On the left menu, select Properties.
4. Click on the application registration to manage additional properties.

5. On the menu on the left select API permissions.
6. On the API permissions page click Add a permission.

7. On the new Request API permissions window on the Microsoft APIs tab select Microsoft Graph API.

8. Choose Delegated permissions for the Microsoft Graph.
9. Use the search in the Select permissions field to find and tick the following permissions:
   • User.Read
   • offline_access
   • Mail.Read
10. If you are planning to use this mailbox to send emails:
    • Mail.Send
11. Click Add permissions.

The added permissions will be displayed in the list:

Do not close the screen just yet. We will need to copy the application data to ShopCtrl.

Step 3. Getting credentials for your Microsoft 365 mailbox synchronization with ShopCtrl

To establish the Graph API connection with your Microsoft 365 account, we need to provide the following information:

• Application (client) ID
• Directory (tenant) ID
• Client secret value

To create and get credentials:

1. Sign in to the Microsoft Azure Active Directory administration console as an admin.
2. In the Azure Active Directory admin center go to the Enterprise applications > All applications
3. Click on the app you created for integration with ShopCtrl. The application details will open.
4. On the left menu, select Properties.
5. Proceed to manage additional properties by clicking on the application registration: "If this application resides in your tenant, you can manage additional properties on the application registration."
6. On the left menu, select Overview.
7. Copy the Application (client) ID and save it to a secure place. It is your Client ID.
8. Copy the Directory (tenant) ID and save it to the secure place. It is your Tenant ID.

9. On the left menu, select Certificates & secrets.
10. Click New client secret.
11. On the Add a client secret pane, enter the Description for a secret.

12. Select the Expires period for the secret. Consider setting up a bigger period.

13. Click Add to generate the client secret.
14. Copy the Value field of the client secret and save it as you would normally do with passwords.

Step 4. Setting up Microsoft Office 365 mailbox synchronization in ShopCtrl

The next step is to enter the credentials for the created application into ShopCtrl and authorize it on Microsoft 365.

Setting up retrieval of the mail

1. On the sales channels panel, click the designated shop icon and select Settings from the list.
2. In the topic menu go to Communication > E-mail > Receiving email.
3. Click Add to create a new connection.

4. Select the Protocol which is Microsoft Graph API in our case.
   
5. Expand Auth Parameters pane and select Microsoft 365 as an Auth method.
6. On the Auth Parameters pane enter the Tenant ID of the application you created.
7. Provide Client ID.
8. Enter Client Secret. The Status field will be changed to Not authorized.
9. Click Save and Authorize. You will be redirected to authorization confirmation. Please make sure there are no unsaved changes on the other tabs. If you proceed, progress on other tabs will be lost.
10. Login to your Microsoft 365 account under the user you are configuring. Review the permissions and confirm granting access.

11. After confirmation a Success window will be displayed confirming that access has been granted successfully for the account. In case any of the auth parameters were provided wrong, a corresponding window will be displayed. Correct the errors and proceed with the same steps.
12. Click the Back to Shop Settings button and you will be redirected back to your ShopCtrl environment.
13. On the shop settings page, the Status of your connection will change to Authorized.
14. Enable the connection on the top of the window.
15. Click Ok to close settings.

Test connection to the mailbox

To test if the mailbox was configured correctly, click the Test MailBox button. The popup message will inform you if the connection was successful.
Once the connection is established, mark the Check mail checkbox to start receiving emails to ShopCtrl.

Setting up sending mail

1. On the sales channels panel, click the designated shop icon and select Settings from the list.
2. In the topic menu go to Communication > E-mail > Sending email.
3. Click Add to create a new connection.
   
4. Select the Protocol which is Microsoft Graph API in our case.
5. Expand Auth Parameters pane and select Microsoft 365 as an Auth method.
6. Enter the Tenant ID of the application you created.
7. Provide Client ID.
8. Enter Client Secret. The Status field will be changed to Not authorized.
9. Click Save and Authorize. You will be redirected to authorization confirmation. Please make sure there are no unsaved changes on the other tabs. If you proceed, progress on other tabs will be lost.
10. Login to your Microsoft 365 account under the user you are configuring. Review the permissions and confirm granting access.

14. After confirmation a Success window will be displayed confirming that access has been granted successfully for the account. In case any of the auth parameters were provided wrong, a corresponding window will be displayed. Correct the errors and proceed with the same steps.
15. Click the Back to Shop Settings button and you will be redirected back to your ShopCtrl environment.
16. On the shop settings page, the Status of your connection will change to Authorized
17. Enable the connection on the top of the window.
18. Click Ok to close settings.

Send test mail

To check if outcoming server details were provided correctly, click Send test mail and enter an email address to send a test email to.