New article: IMAP, OAuth2 and Microsoft 365


here is a new how to article about integrating with IMAP using OAuth2 and Microsoft 365.




Have been trying to replicate this tutorial with no luck so far.Firstly I have a couple of question.

I am having trouble understanding the link between the Office 365 connection and the IMAP (OAUTH2) connection. Is that via Tenant ID and Client ID matching ? That is my assumption, but would like that clarified if possible.

We have a pre-existing standalone python application processing email from Office 365 via IMAP utilising OAUTH2 however the same connections (using the same information) does not work using Zato.

We have to define a specific tenentid so our end point is different and the Tenant ID is a large GUID like value not a name

Same for the Client ID

This seems a bit at odds with your example setup.

We also found that (when trying to get another application (ITOP)) to communicate with Office365 (with explicit tenantud) they’re endpoints are not correct and it too is unable to connect. Their first implementation is also based on end points, which doesn’t work with a single tenant (unable to use multitenant endpoints)

This is recognised by iTop team and a code change is being worked on at the moment. You can see this in their ticket iTop - IT Service Management & CMDB / Tickets / #2107 Tenant should be configurable when using OAuth2

Auth and token endpoints for oauth2 in a single tenant are respectively<our organization's tenant UUID>/oauth2/v2.0/authorize
and<our organization's tenant UUID>/oauth2/v2.0/token

I have tried configuring the first step based on the information I have, ping doesn’t error, but logs don’t show any information as such.

Creating and (pinging) the IMAP connection results in an error

2022-12-22 05:05:01,956 - INFO - 3194:Dummy-455 - - Microsoft 365 ping result (TEST IMAP) -> `None`
2022-12-22 05:05:02,179 - ERROR - 3194:Dummy-455 - O365.connection:0 - Client Error: 401 Client Error: Unauthorized for url:<USRENAME>/mailFolders?%24top=999 | Error Message: Access token is empty.
2022-12-22 05:05:02,203 - ERROR - 3194:Dummy-455 - - Caught an exception, cid:`b4803d9c97468e0a36779a9d`, status_code:`HTTPStatus.INTERNAL_SERVER_ERROR`, `Traceback (most recent call last):
  File "/opt/zato/3.2.0/code/zato-server/src/zato/server/connection/http_soap/", line 343, in dispatch
    response = self.request_handler.handle(cid, url_match, channel_item, wsgi_environ,

  File "/opt/zato/3.2.0/code/lib/python3.8/site-packages/O365/", line 798, in _internal_request
    raise HTTPError('{} | Error Message: {}'.format(e.args[0], error_message), response=response) from None
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: | Error Message: Access token is empty.

So currently not sure if it is just mis-configuration on my part or the API utilisation is correct for single tenant instance.



Hi Tim,

I am assuming that you are using the latest Zato version.

If yes, then I can confirm that the information from the article is correct and that is how you can configure Microsoft 365 IMAP connections. There are various production environments that use this capability.

There are four elements needed:

  • An email address
  • Application (client) ID
  • Tenant (directory) ID
  • Client secret

Whether they are a GUID or in another form does not matter and Zato does not inspect these values in any way, they are passed directly to Microsoft 365 APIs.



Yes I am running the latest builds.
But as I pointed out, the zato appears to not be using the oauth2.0 URL end points as per my post, but oauth 1.0.

We found the only way to connect to a single tenant is to use the oauth2 endpoints. Which was also required for a standalone python application. And iTop team are doing an update to their oauth IMAP extension to use the oauth2 endpoints as multiple people are unable to connect (auth failure) with out manually patching the underlying libraries;


Hello Tim,

currently, I will not be able to analyze this subject further seeing as there is no commercial client requiring the capability that you are requesting.

You can find the source code of IMAP connections at the address below. If you tell me exactly what to change and how to test it, I will add it to the development roadmap.