Setting up OAuth2 with Outlook

If you want to use older desktop Outlook versions with OAuth2, read here about proxying OAuth2 connections with EmailEngine.

EmailEngine has native support for Gmail and Outlook (Hotmail.com, MS365, and such) OAuth2 accounts. How to use OAuth2 with Gmail has been covered before. In this post, we will look at Outlook.

Even though this post describes setting up OAuth2 with EmailEngine, the same applies to any other IMAP/SMTP client as well, where you would need to provide the OAuth2 credentials in order for the mail application/library to work.

To start, we need to navigate to and log in to Azure Active Directory. Just as with Gmail, we need to create an application that will manage the credentials, so open the "App registrations" page and hit the "New registration" button.

To set up the application, there are three values to fill in. First is the application name. Whatever you choose here will be shown later to the users in the authorization form, so make it something easy to understand.

Then we need to select which kind of account types we will support. The easiest would be to go with "Personal Microsoft accounts only," as this does not need any kind of validation at all, but the downside is that you are pretty much stuck with hotmail.com addresses only. Great to test things out, but it is not so good for production apps.

Finally, you have to set the application callback URL. This is basically your EmailEngine's base URL prefixed by "/oauth". Beware though that you either have to provide a valid HTTPS URL or, alternatively a "http://localhost" URL. You can not use the localhost IP address, that is, "http://127.0.0.1", as, for whatever reason, it is not allowed.

Now we have our application, and we can already get the first required identifier, the "Application ID" that we later need to set up OAuth2 support in EmailEngine.

To continue setting up the application, click on the "API permissions" menu link.

Here on the API permissions page, we can set up the permissions our application requires. By default, there's only "User.Read". We can't do much with this permission, so click on the "Add a permission" button to add the rest.

All the permissions we need can be found in the default "Microsoft Graph" section, so click on the large button to continue.

Depending on your account type, you might also be presented with a choice between delegated and application permissions. Choose the delegated option.

First, search for "IMAP" and mark the "Imap.AccessAsUser.All" checkbox. This is needed to read emails from an IMAP account.

Next, do the same with SMTP. This is needed to send emails via SMTP.

And finally, search for and mark the "offline_access" permission. This gives us the capability to refresh expired access tokens. That's it for now. Click on the "Add permissions" button to continue.

We should see all the permissions we require listed on the overview page. If everything seems fine, then we are done with this topic and can continue. Click on the Certificates & secrets menu link.

This is the main part where we can generate a client secret needed by EmailEngine. Click on the "New client secret" button to create one.

Not much to see here. Set some kind of name for the new secret and choose an expiration time you're fine with.

Once the credentials are created, we should see the actual secret value. Make sure to copy this value (the one in the "Value" box), as it's not shown anymore once you close this page. This is the "Client Secret" for EmailEngine.

We have all the values we need, so we can start configuring EmailEngine to support Outlook OAuht2 authentication. Navigate to Configuration->OAuth2. Click on the "Create new" button and then select "Outlook" as the type of the app.

NB! EmailEngine only operates on https://outlook.office.com/ APIs, not https://graph.microsoft.com/

Use the Application Id and Client secret values you got from the Azure portal. The redirect URL must be exactly the same one you used when registering the application.

"Account types" value depends on the type of accounts your application supports. For example, the default "consumers" is for Microsoft accounts (e.g., Hotmail). "organizations" allows MS365 accounts, and "common" supports both. If you want to support a specific organization only, you can use the Directory ID value for that organization, like "f8cdef31-a31e-4b4a-93e4-5f571e91255a".

Also, make sure to mark the "Enable this app" checkbox, or the Outlook option does not become available in hosted account setup forms.

Now we can open the accounts page and click on the "Add an account" button. Set some name and account ID values and click on the "Continue" button to do so.

Click on the "Sign in with Microsoft" button.

If you are not yet logged in to Outlook, you will have to do so. Once you are authenticated, you will be displayed the following slightly scary-looking form. Don't be afraid and click on "Yes". If you are using an MS365 account, you might see a different page, for example, a warning that the admin of the domain has not accepted your application. Getting these things correct is out of the scope of the current blog post.

That's pretty much it, then. If all succeeded, the account should be listed and should switch into the"connected" state in a moment.

IMAP and SMTP permissions

If you are managing an MS365 organization and EmailEngine cannot connect to IMAP or SMTP of the email accounts you manage, you might need to enable support for these protocols manually. Navigate to https://admin.microsoft.com/ and enable IMAP and SMTP, as shown in the image below.