Connect FreeScout to Microsoft 365 Exchange via OAuth

If you need to connect a shared Microsoft 365 mailbox to FreeScout you need to apply a Business Basic license to the shared Microsoft 365 mailbox (or Microsoft Exchange Online Kiosk license - read more here).

Sending Emails

Sending and fetching emails works via the same Microsoft Exchange app (you don't need to create two different Microsoft Exchange apps). Instructions on how to create and configure the app are provided below in "Fetching Emails" section.

If you haven't been using SMTP, you may need to enable it using these Microsoft instructions. You'll also have to set a password if using a shared mailbox, and you may have to disable security defaults in Azure or it will override SMTP settings. Connection details for FreeScout are provided here.

If you are receiving CN='your.server.com' did not match expected CN='smtp.office365.com' error - see this.

Keep in mind that invitations to users are sent not on behalf of some mailbox but using global "System Emails" settings under "Manage > Mail Settings". And System Emails can't be sent via OAuth - use some SMTP server with login/password authentication.

Here are "Sending Emails" connection details:

• Protocol: SMTP
• Server: smtp.office365.com
• Port: 587
• Encryption: TLS

Fetching Emails

Keep in mind that sometimes MS365 mail is experiencing some technical issues which may result in errors like connection setup failed or Connected, but no IMAP folders found.

The MS365 user you will be using to connect to FreeScout must have a MS365 mailbox and a license allowing to access it (try to open https://outlook.office365.com/mail/). Also make sure to disable Dynamic attachment scanning in MS365 (see this issue).

1. Register an app in "Azure Active Directory » App registrations » New Registration". Select "Accounts in any organizational directory (Any Azure AD directory - Multitenant) " in Supported account types. Set Web as Redirect URI and enter URL: https://yourdomain.com/mailbox/oauth (make sure to change the domain to yours). Also you can read more on creating Microsoft Exchange apps here.

2. In the app settings in "API permissions" click "Add a permission", then click "Microsoft Graph" and choose Delegated permissions: IMAP.AccessAsUser.All, Mail.Read, Mail.Read.Shared, Mail.ReadBasic, Mail.ReadBasic.Shared, Mail.ReadWrite, Mail.ReadWrite.Shared, Mail.Send, Mail.Send.Shared, offline_access, SMTP.Send, User.Read.

3. In "Authentication » Supported account types" make sure that Accounts in any organizational directory (Any Azure AD directory - Multitenant) is selected.

4. Open app's Overview copy "Application (client) ID" to FreeScout into Username field in "Fetching Emails" for the mailbox.

5. Create secret in "Certificates & secrets" (set expiration date as far as possible - usually 2 years) and copy Secret Value (not Secret ID!!!) to FreeScout into Password field in "Fetching Emails" for the mailbox.

6. In "Fetching Emails" enter connection details and save settings:

• Protocol: IMAP
• Server: outlook.office365.com
• Port: 993
• Encryption: SSL

7. Click "Connect" next to "Microsoft Exchange" and authenticate Microsoft Exchange under the user corresponding to the email address your are using for the mailbox in FreeScout ("Connect" button appears only after you enter Username and Password).

Make sure to authenticate in Microsoft Exchange under mailbox user!!! Otherwise you will be getting "Connected, but no IMAP folders found" error (like in this case)

Troubleshooting OAuth Emails Fetching

If you need to debug the process of fetching emails via IMAP & OAuth, add APP_DEBUG=true to the .env file and clear cache. After that run the following console command which will show the process of interaction between FreeScout and MS365 IMAP server:

php artisan freescout:fetch-emails

After that you can also connect via console directly to the MS365 IMAP server and pass obtained from php artisan freescout:fetch-emails instructions:

openssl s_client -crlf -connect outlook.office365.com:993

— Emails are fetched from MS365 mailbox without attachments.

Disable Dynamic attachment scanning in MS365 (see this issue).

— If you see "Error: connection setup failed" in logs from time to time

Check "Manage » Logs » Fetch Errors". If you see something like "Error occurred refreshing oAuth Access Token: The redirect URI 'http://example.org/mailbox/oauth' specified in the request does not match the redirect URIs configured for the application" it means you need to add 'http://example.org/mailbox/oauth' to the App settings in Azure.

Try to increase "Fetching Interval" in "Manage » Settings » Mail Settings". If it does not help - just ignore it (see this discussion).

— Error: connection failed; File: /overrides/webklex/php-imap/src/Connection/Protocols/ImapProtocol.php

This may mean that something is wrong in "Fetching Emails" settings - check Server, Port, etc.

— Connected, but no IMAP folders found

Sometimes it may be related to technical issues in MS365 or you can try this solution.