Troubleshooting email

Table of Contents



It may happen you run into an error when configuring Exchange or you see error messages in the email live tile. This article will help you to troubleshoot these issues. 


Why do we use integration credentials?

Workspace 365 uses oAuth2 configuration to enable SSO. This makes it possible to retrieve user data from Microsoft Entra ID (previously called Azure AD), such as Exchange Online information, without further configuration. However, to an On-Premise Exchange environment we cannot connect via oAuth2. Therefore we use integration credentials. 

Back to top


Should I keep the UPN and Primary SMTP address the same?

Workspace checks for the user's UPN and not the primary SMTP address. We recommend to keep these equal to each other to prevent issues. 

If this is not the case, you have two options:

  • Add the mailbox from the email app under "managed mailboxes" and use this as the "default send address".
  • You can make use of the integration credentials. The user will have to fill these in manually, before they can access Exchange. 

Back to top


Images are not automatically shown ("Sender images")

Administrators can configure the default visibility of images in the email under Settings > Email. This option is called "Sender images".

These may contain suspicious content, such as spam, viruses and malware. By showing images automatically, the user might download suspicious content directly to their device when opening an email.


Back to top


Autocomplete does not work

Explanation: when typing in a recipient's email address in a new email, autocomplete does not work.

Solution: this is caused by a missing or incorrect API permission on the SSO app registration. The People.Read permission is required for this. Refer to Manual setup of SSO for the full list is required permissions and update your SSO app registration accordingly.

Back to top


Error messages & Solutions

"Unable to connect to Exchange Online/Office 365"


Explanation: you receive the error message "Unable to connect to Exchange" during the Exchange Online configuration.

Solution: from the Workspace settings page, disable the integration credentials (these are mostly used in an On-Premise Exchange configuration).

Back to top


"Your changes are not saved. Your Exchange URL is not valid" or "Exchange URL is not valid"


Explanation: Exchange is enabled. When filling in the URL, you receive the error message that the URL is not valid. 

Solution: When clicking on "Detect" (Autodiscover), the Exchange server URL is retrieved automatically from Office 365. After enabling Exchange from the Workspace settings (Integrations > Exchange settings), the URL should be filled in automatically.
In case of an On-Premise Exchange, fill in the URL manually and click on "Done" (using Autodiscover will result in an error).

Back to top


"Your email has not been configured" or "The connection to Exchange is not configured, therefore..."


Explanation: this error message occurs in the email live tile after migration from On-Premise Exchange to Exchange Online, or Exchange has not been configured at all.


  • Make sure that Exchange is enabled. More information on how to set up Exchange, click here.
  • Migration to Exchange Online? Users will have to fill in their email credentials once (there is no other workaround for this). This is due to the fact that Exchange already has been configured once before/written in a database. By filling in the credentials, users can reconnect to Exchange Online. Also make sure the integration credentials are disabled.


Back to top


"Unknown error during retrieval of unread messages"

Explanation: the error message "Unknown error during retrieval of unread messages" appears in the email live tile. 

Solution: this error can be related to an issue with OAuth2, e.g. when integration credentials are being used when they should be disabled. Always make sure the appropriate API permissions for Exchange are granted in Microsoft Entra ID (with admin consent) and, when available, check the Workspace error logs for more information.


Back to top