Mail Integration Plugin for Office 365

Support-ending notice

Early November 2022, ownership of the Mail Integration for Office 365 / Outlook plugin transferred to WPO365. We are committed to provide (best-effort based) support for this plugin until the end of 2023.

To ensure, however, that we are able to provide you with long time support, we urge you to download and install the WPO365 | MICROSOFT GRAPH MAILER plugin for WordPress instead (and de-activate the Mail Integration for Office 365 / Outlook plugin and remove it from your WordPress website).

If you have already installed and configured the Mail Integration for Office 365 / Outlook plugin, then please make sure to check out our easy-to-understand online migration guide.

- Marco van Wieren | Downloads by van Wieren | https://www.wpo365.com/

What does it do?

Put simply, the plugin relays all emails sent from WordPress through your Microsoft email account. This helps improve the deliverability of your WordPress mail, as Microsoft’s mail servers are set up to avoid being flagged as spam and should already be configured as the trusted mail server for your domain.

Please note The account cannot be a free account such as Live, Outlook.com, Hotmail etc. as Microsoft has not enabled the Graph API for such accounts. The plugin should however work with the paid for personal and business versions of Office 365, Outlook and Microsoft Exchange.

Great, but why another WordPress mail plugin?!

Microsoft has disabled basic authentication (username and password) over the SMTP protocol, requiring more modern and secure methods of authentication such as OAuth 2.0 (the protocol used by this plugin). As such, most of the SMTP plugins available do not support Office 365 / Outlook, or if they do, the functionality is a paid-for feature.

Without going into too much detail, OAuth 2.0 requires a client (in this case our WordPress Plugin) to request access to our mail server using Microsoft Graph using the four pieces of information outlined below.

Application / Client ID This is the ID of technical user (the so-called App principal) that you create in your Azure AD that represents your application (in this case your WordPress website) and that is used when the plugin connects to Microsoft Graph.
Application / Client Secret Think of this secret as the password for the technical user above.
Tenant ID: This lets Microsoft know which identity provider - your Azure AD instance - to go to when the plugin tries to authenticate when it connects to Microsoft Graph.
Redirect URI: This is the location to which the identity provider will send an access code that can then be used by the plugin to connect to Microsoft Graph.

Great, so what are the prerequisites?

You are a Global Administrator for your company’s Microsoft 365 tenant / Azure AD (or at least know someone in your organization who has sufficient privileges to edit the Azure Active Directory App registration(s) that was created previously to add the Mail.Send delegated or application-level permission and grant consent as an administrator).
You have at least one Microsoft 365 with a license that includes an Exchange Online Mailbox.
You are an Administrator for your WordPress website.

Step 1 – Download and Install

The plugin can be downloaded from the WordPress plugin repository (link provided below) or installed from the Plugins area of the admin side of your site. Remember to activate the plugin after installation!

WPO365 | Mail Integration for Office 365 / Outlook – WordPress plugin | WordPress.org

Step 2 – navigating to the plugin settings

Once you have installed and activated the plugin, you will need to navigate to the plugin settings page. This can be found under the WordPress settings menu, titled Mail Integration 365 Settings’, as pictured below.

The page itself looks as follows.

The other steps explain where to get the various required fields. However, for now, please simply copy the Redirect URI field value and paste this somewhere so you can refer back to it (as it is required in Step 6 below). Make sure you copy the whole URI (when you click the box it will select the entire URI, highlighting it blue to indicate the selection).

Step 3 – creating and registering the Azure Active Directory Application

App registration

In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
Navigate to Azure Active Directory > App registrations.
Click + New registration.
On the Register an application page appears, enter your application’s registration information.
- Name Enter a meaningful application name that will be displayed to users of the app.
- Supported account types Select Accounts in this organizational directory only
- Redirect URI Select the Web platform and paste the Redirect URI that you copied at the end Step 2 previously.
Click Register to create the App registration in Azure AD.

Please note The Redirect URI that you enter for your App registration in Azure AD must be exactly the same as the URL that the plugin proposed.

API Permissions

Click API permissions from your App registration's menu on the left.
Click + Add permission.
Select Microsoft Graph > Delegated permissions.
Ensure that the following permissions are already checked (or check them if not):
- openid
- profile
- email
- User.Read
- offline_access
Scroll down to Mail and check
- Mail.Send
Click Add permissions.
Wait until Grant admin consent for … has become available, then click to grant consent for all users in your tenant to use this ‘App registration’.

Please note To successfully authorize the WordPress application to send emails using Microsoft Graph as a specific user you must have added (and granted admin consent for) at least the delegated API permissions as shown in the previous screenshot.

Important Customers with advanced Azure AD management skills might be interested to grant consent on behalf of a single user instead. Microsoft has prepared this article that explains the steps that are required to accomplish this using PowerShell. In this case the administrator has not granted consent for all users to use the Mail.Send permission but for a single user only (which must be the account that is used in the next step to complete the mail authorization configuration

Certificates & Secrets

Perform the following steps to create an application client secret.

Click Certificates & Secrets from the App registration menu on the left.

Click + New client secret.
Optionally, you can give the new secret a Description that helps you remember it later and choose an expiry date e.g. 6 Months *.

Copy the secret's Value (not its ID) ** and temporarily paste it in a text file. You won’t be able to retrieve it later.

* Once a password expires, it cannot be used and the plugin will fail to retrieve tokens. Therefore you must renew this password right before it expires and update the plugin's configuration accordingly (see next step).
** Make sure to copy the value and not the Secret ID. You wouldn't be the first!

Step 4 – copying the Client ID and Tenant ID to the plugin settings

To get the Application (client) ID and Directory (tenant) ID, we need to navigate to the Overview page of our Azure Active Directory Application. Here you will find both the Application (client) ID and Directory (tenant) ID. If you’ve closed the application page from Step 4, you can get to this again by logging back into Azure Active Directory, navigating to ‘App registrations’, and then clicking on your application from the shown list.

Step 5 – authorizing WordPress to use your Microsoft Account

The final required step is to authorize your WordPress installation to use a Microsoft 365 mailbox to send emails from. To do this we need to go back to the plugin settings page within the WordPress administration area.

Provided you have followed Steps 1 – 4 above, you should now see an Authorize button as pictured below. When you click this button, you will be redirected to a login page where you need to enter the login details for your chosen Microsoft Account (the account you wish your emails to be sent from).

Important If your browser is set to remember the login details for a different Microsoft Account to the one you wish to register with the plugin. To avoid the browser automatically using these saved credentials and registering the wrong account with your plugin, you should open a new in-private/incognito browser window before logging in to WordPress. You can then follow all the setup steps listed above. This will ensure that when you click the authorise button on the plugin settings page, you are prompted for the credentials of the account you wish to use, rather than logging you in automatically with your own saved account credentials and linking WordPress to the wrong account!