Send email using Microsoft Graph Mailer

Use this guide if you want to configure the WPO365 | MS GRAPH MAILER and send transactional WordPress emails from one of your Microsoft 365 Exchange Online / Mail enabled accounts using Microsoft Graph instead of - for example - using SMTP.

The  WPO365 | MS GRAPH MAILER plugin for WordPress is a spin-off and derived from the popular  WPO365 | LOGIN plugin that allows your WordPress website users to sign in with their corporate Azure AD / Microsoft Office 365) account: No username or password required.

If your intention is to connect WordPress and Azure AD / Microsoft 365 beyond the scope of just sending emails then please remove the WPO365 | MS GRAPH MAILER plugin and instead install the WPO365 | LOGIN plugin (which includes the exact same email sending functionality plus a lot more e.g. to enable Microsoft based single sign-on).

Features

WPO365 | MS GRAPH MAILER (Free)

  • Delivery Send WordPress transactional emails from one of your Microsoft 365 Exchange Online / Mail enabled accounts using Microsoft Graph instead of - for example - SMTP.
  • Choose between sending emails using application-level permissions to send emails as any user and sending emails using delegated permissions (= recommend) to send emails as one specific authorized user.
  • Save to Sent Items Emails sent will be saved in the Microsoft 365 account's mailbox in the Sent Items folder, further helping to track (successful) mail delivery.
  • Send as HTML Send emails formatted as HTML.
  • Attachments Send files from your WordPress website as attachments.
  • Configuration / Test Easy configuration with detailed step-by-step Getting started guide and ability to test the configuration by sending a test email to various types of recipients incl. CC, BCC, optionally with attachment.
  • Support for WordPress Multisite.

WPO365 | MAIL (Paid premium extension)

  • Use WP-Config for AAD-secrets Further improve overall security by choosing to store Azure Active Directory secrets in your WordPress WP-Config.php (on disk) and have those secrets removed from the database.
  • Mail audit / resend Log every transactional email sent from your WordPress website, review errors and try to send unsuccessfully sent mails again.
  • Allow forms to override "From" address Allow other plugins e.g Contact Form 7 to dynamically configure the account used to send the email from. If the dynamically configured "From" address appears not to have the same domain ending as the default "From" address, the plugin will use the default "From" address instead.
  • Send as BCC Send emails as BCC instead and prevent reply-to-all mail pollution.
  • Reply-to Configure a default reply-to mail address if this should differ from the account's mail address that is used to send WordPress transactional emails from.

Visit our website for details and pricing.

Before you start

  • You are a Global Administrator for your company’s Microsoft 365 tenant / Azure AD directory or have at least sufficient privileges to register a new application in Azure Active Directory.
  • You are an Administrator for your WordPress website.

Option 1: Send mail using delegated permissions (recommended)

Sending WordPress emails using delegated permissions is currently your best option, unless you have a requirement to send WordPress emails from more than one address, for example using different Contact Form 7 forms. In that case you would need to configure application-level permissions. However, the use of application-level permissions to send emails as any user means great responsibilities and you must ensure that your website is protected at all times!

Perform the following steps to enable your WordPress website to send emails using Microsoft Graph using delegated permissions.

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 enter your website's home address as absolute URL e.g. https://test1.wpo365.com/.
  • 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 proposes when you go to WP Admin > WPO365 > Mail. To avoid any issues you should copy the URL from here (see screenshot below).

ID Token configuration

When the plugin authorizes the user's mail account it will also request an ID token so it can perform a check to make sure that the account details match. 

Perform the following steps to configure some of the fields (so-called claims) of the ID token.

  • Click Token configuration from the App registration's menu on the left.

  • Click + Add optional claim.
  • Select ID.
  • From the list check the following options
    • email
    • upn
  • Click Add.
  • If you are asked to add the email and profile permissions required for these fields to be sent in the ID Token then confirm by clicking yes (see the next step).

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!

Configure the Microsoft Graph Mailer for WordPress

  • To reconfigure your website and send WordPress emails using Microsoft Graph you must check the corresponding option, as shown below.

  • Immediately after sending emails with Microsoft Graph is enabled, the plugin starts to search for an existing mail authorization configuration. If no previous configuration exists, all fields in the section Azure Active Directory registration will first appear empty. To complete the mail authorization configuration, you must now supply the Directory (tenant) ID, Application (client) ID and an Application (client) secret of the App registration that you created in the previous step. You will find the Directory (tenant) ID and Application (client) ID on the App registration's Overview page. The Application (client) secret you should have saved temporarily in a text file.

As soon as you all three fields Directory (tenant) ID, Application (client) ID and Application (client) secret are filled out, you will notice that the plugin again starts to search for an existing mail authorization configuration because a spinner will turn to right of the Authorize button. Also note that the Refresh button to right of the Authorization status field allows you to manually start this search again.

  • Enter the mail account that you want to use to send all WordPress emails from. Please note that the account's username is not necessarily the same as the mail account's email address.
  • Finally click Authorize to initiate the mail authorization flow. 
    • You will be redirected to https://login.microsoftonline.com/.
    • You will be asked to sign in with the mail account's user and must enter the password for that user.
    • After you authenticated successfully, you will be redirected back to the website and to the plugin's Mail configuration page.
    • The plugin will again start to search for an existing mail authorization configuration. Since you authenticated successfully, the plugin should now be able to retrieve the mail authorization configuration and show Authorized! to the right of the Authorize button.
    • If an error occurred during any of the previous steps, the plugin will display an error message. You can also navigate to WP Admin > WPO365 > ... > Debug and check here for any errors of warnings.

  • To delete an existing mail authorization configuration, simply uncheck the box Delegated permissions.

At this point, you configured the WPO365 | LOGIN plugin to send WordPress emails using Microsoft Graph using delegated permissions. Now please scroll down to Test the Microsoft Graph Mailer for WordPress to test the configuration you just applied.

Option 2: Send mail using application-level permissions (send mail as any user)

Sending WordPress emails using application-level permissions means that you allow the application to send emails as any user, which means great responsibilities and you must ensure that your website is protected at all times! However, if you have a requirement to send different WordPress emails from different accounts and you feel that you cannot resolve this by sending all emails from the same account but with - for example - different reply-to addresses, then configuring application-level permissions may be your only option.

Perform the following steps to enable your WordPress website to send emails using Microsoft Graph using application-level permissions.

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 Leave empty
  • Click Register to create the App registration in Azure AD.

API Permissions

  • Click API permissions from your App registration's menu on the left.
  • Remove the User.Read permission by selecting Remove permission from the menu on the far right.

  • Click + Add permission.
  • Select Microsoft Graph > Application permissions.
  • 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’.
At this point you must be aware of the fact that you have now granted an application identity the unlimited permission to send emails as any user in your organization and ensure that you have taken sufficient precautions to protect your website against attacks

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!

Configure the Microsoft Graph Mailer for WordPress

  • To reconfigure your website and send WordPress emails using Microsoft Graph you must check the corresponding option, as shown below.

  • Immediately after sending emails with Microsoft Graph is enabled, the plugin start to search for an existing mail authorization configuration. If no mail authorization exists, all fields in the section Azure Active Directory registration will first empty. To complete the mail authorization configuration you must now supply the Directory (tenant) ID, Application (client) ID and an Application (client) secret of the App registration that you created in the previous step. You will find the Directory (tenant) ID and Application (client) ID on the App registration's Overview page. The Application (client) secret you should have saved temporarily in a text file. 

As soon as you all three fields Directory (tenant) ID, Application (client) ID and Application (client) secret are filled out, you will notice that the plugin again starts to search for an existing mail authorization configuration because a spinner will turn to right of the Authorize button. And the Refresh button to right of the Authorization status field allows you to manually start this search.

This time the search should be able to detect that you have reconfigured the API Permissions for the registered application and as a result the Authorization status should show that Application-level permissions have been detected, as shown below.

Please note Starting with version 19.0 of the WPO365 | LOGIN the plugin supports sending WordPress emails using delegated permissions, which has since also become the recommended way. Therefore the plugin will show a warning and recommends that you remove the application-level permissions and instead configure delegated permissions. But obviously, if you have good reasons to configure application-level permissions that you can safely ignore the recommendation.

  • Since you configured application-level permissions you should NOT click the Authorize button. However, if you do, you'll see a notice that you should not click it if you're configuring the plugin to use application-level permissions and you can click to cancel the mail authorization flow.
  • Enter the mail account that you want to use to send all WordPress emails from. Please note that the account's username is not necessarily the same as the mail account's email address.

Perform the following steps to remove application-level permissions to send WordPress emails using Microsoft Graph.

  • Navigate to your App registration in Azure AD e.g. by click the link View in Azure Portal for the Application (client) ID field on the plugin's Mail configuration page.
  • Continue to the API Permissions page.
  • From the list, delete the application type permission for Mail.Send.
  • Grant consent as an administrator and confirm that you would like to remove the permissions that you just deleted altogether.
  • Return to the plugin's Mail configuration page and click the Refresh button to the rights of the Authorization status field.

At this point, you configured the WPO365 | LOGIN plugin to send WordPress emails using Microsoft Graph using application-level permissions. Now please scroll down to Test the Microsoft Graph Mailer for WordPress to test the configuration you just applied.

Test the Microsoft Graph Mailer for WordPress

  • To test the configuration you can enter comma separated email addresses for the following recipients:
    • To recipients
    • CC recipients
    • BCC recipients
  • Optionally you can also add an attachment when sending the test email.

  • Finally click Save configuration + Send test email and wait for the corresponding Feedback.

Adding premium features

You can unlock the premium features by purchasing the WPO365 | MAIL extension (see our website for details and pricing). The extension must be installed in addition to the WPO365 | MS GRAPH MAILER plugin.

Configure premium features

  • If you want to further improve the overall security you can choose to add the confidential values to your WP-Config.php. If enabled those values are removed from the database.
  • Allow forms to override "From" address Allow other plugins e.g Contact Form 7 to dynamically configure the account used to send the email from. If the dynamically configured "From" address appears not to have the same domain ending as the default "From" address, the plugin will use the default "From" address instead. Please note that this feature is only available when you configured application-level permissions.
  • You can send emails with a Reply-to address that is different from the address sending the email.
  • If you are regularly sending emails to multiple (CC) recipients you can Send to BCC instead. When you check this option all to and CC recipients will be configured as BCC recipients instead and the email will be sent to the Default To: recipient's email address that you must enter in the corresponding field.
  • You can enable the mail audit / resend functionality that will help you monitor emails sent and gives you an opportunity to resend emails that failed to send. See the following paragraph for details.

Mail Audit / Resend

If you check the premium option to Log all emails sent from your WordPress website, the plugin will save all sent items in the database.

When you checked this option, a link to View logs will be shown and allow you to review errors and try to send unsuccessfully sent mails again.

Troubleshooting

If the test email was not sent successfully you may check the plugin's debug-log for any errors.

You can reach the WPO365 team for support and questions in one of the following ways:

  • Click the Contact link at the top of this page.
  • Use the Beacon by clicking the question mark in the blue dot on the plugin's configuration page.
  • Fill out the Contact Form on the website.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us