Setting up Email protocols to 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 pop3/imap and smtp protocols.

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

Video Instructions. Setting up your Microsoft Office 365 mailbox in ShopCtrl

Step 1. Configure your Microsoft Office 365 user apps access permissions

1. Log in to your Microsoft admin console.
2. Click on the ☰ menu in the top left corner and go to Users > Active users.
3. Select your shop user and click on the User name to open preferences.
4. Go to the Mail tab and click the Manage email apps link.

5. Choose apps the user can use to access their Microsoft email:
6. Depending on a protocol you are planning to use, choose either Pop or IMAP.
7. (Optional) If you are going to use the Microsoft SMTP server to send emails, check the Authenticated SMTP as well.

8. Click Save changes.

Step 2. 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.

Grant permissions to the ShopCtrl application

To complete application registration, we need to grant new app API permissions to retrieve mail via Pop or IMAP, and (optional) send mail via SMTP protocol.

1. To add minimal required API permissions to the new app:
2. Go back to Enterprise applications > All applications.
3. Click on the app you just created. The application details will open.
4. On the left menu, select Properties.
5. Click on the application registration to manage additional properties.

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

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

9. Choose Delegated permissions for the Microsoft Graph.
10. Use the search in the Select permissions field to find and tick the following permissions:
    • offline_access
11. Depending on the protocol you are planning to use:
    • POP.AccessAsUser.All
    • or IMAP.AccessAsUser.All
12. If you are planning to use this mailbox to send emails:
    • SMTP.Send
13. 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 4. Getting credentials for your Microsoft 365 mailbox synchronization with ShopCtrl

To get the incoming and outgoing server settings please visit Microsoft 365 documentation POP, IMAP, and SMTP settings

To establish the 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 5. 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.
Please check Microsoft support pages to get the up-to date server settings.

Setting up the outcoming mail server

1. Log in to your ShopCtrl environment as a user with Shop Owner admin role.
2. On the sales channels panel, click the designated shop icon and select Settings from the list.
3. In the topic menu go to Communication > E-mail > Sending email.
4. Enter the Mail address you are configuring.
5. Click Add to create a new connection.
   
6. Provide the SMTP Server for your Microsoft 365 mail account.
7. Enter the SMTP Port to use for connecting to the mail server.
8. Mark the Use SSL checkbox.
9. Expand Auth Parameters pane and select Microsoft 365 as an Auth method.
10. Enter the Tenant ID of the application you created.
11. Provide Client ID.
12. Enter Client Secret. The Status field will be changed to Not authorized.
13. 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.
14. 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.

Setting up the incoming mail server

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 Protocol you are going to sync mail with: POP3 or IMAP.
5. Provide the Server of your mail account (POP3 or IMAP accordingly).
6. Enter the Port to use for connecting to the mail server (POP3 or IMAP accordingly).
7. Mark the Use SSL checkbox.
8. Expand Auth Parameters pane and select Microsoft 365 as an Auth method.
   
9. Enter the Tenant ID of the application you created.
10. Provide Client ID.
11. Enter Client Secret. The Status field will be changed to Not authorized.
12. 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.
13. 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.

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.