Send email using Microsoft Graph Mailer

Preview notice

We are working hard on a new  WPO365 tutorials site and we are very happy to invite you to visit instead the tutorial to configure WordPress to send emails using Microsoft Graph.

Use this guide if you want to configure the WPO365 | LOGIN or WPO365 | MICROSOFT GRAPH MAILER to send WordPress emails from one of your Microsoft 365 Exchange Online / Mail enabled accounts using Microsoft Graph instead of SMTP with delegated permissions. Make sure to watch the companion video for this article https://youtu.be/1CK7Fl8f8iA.

Please note 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 de-activate and delete 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 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 (must be less than 3 MB in size).
  • 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)

  • Enable sending WordPress emails with attachments larger than 3 MB using Microsoft Graph.
  • Send WordPress emails as / on behalf of another Microsoft User Mailbox or Distribution List.
  • Send WordPress emails from a Microsoft 365 Shared Mailbox.
  • 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

  • Make sure that you deactivate all other WordPress plugins capable of sending WordPress emails e.g. WP Mail SMTP and Mail Integration for Office 365 / Outlook.
  • 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.
  • If you already registered an application (created an App registration) in Azure AD for your WordPress website (e.g. to enable Microsoft based Single Sign-on or Azure AD User synchronization using any of the WPO365 features), then you can skip Step 1 below.
  • Sending WordPress emails using delegated permissions is currently your best option, unless you have a requirement to send WordPress emails from more than one email address. Please refer to this guide to configure the plugin to send emails using application-level permissions.

Important info (for new Microsoft 365 subscriptions)

If you purchased your Microsoft 365 subscription less than 90 days ago, or if you are still in your trial period and have not paid for your subscription yet, then please continue reading.

Exchange Online assigns a ranking to clients that would like to send emails. Subscriptions that are less than 90 days old, have not yet a ranking that allows them to send emails outside of the own organization. Therefore administrators may experience the following behavior. After configuring the WPO365 Microsoft Graph Mailer and sending a test email to an email address outside of the own organization, the plugin reports back that the email was submitted successfully. However, in reality, that email failed to deliver.

To work-around this, administrators can contact Microsoft Support e.g. via https://admin.microsoft.com/ > Show All > Support > Help & support and ask for this limitation to be lifted.

Step 1 - 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).

Step 2 - ID Token configuration

When the plugin authorizes the user's mail account it will also request an ID token to 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).

Step 3 - 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
  • If you need to send attachments larger than 3 MB from WordPress (this is a premium feature and requires the WPO365 | MAIL extension), then the plugin must be able to create a draft email before sending it and you must additionally check
    • Mail.ReadWrite
  • If you need to send WordPress emails from a Microsoft 365 Shared Mailbox (this is a premium feature and requires the WPO365 | MAIL extension), then you must check
    • Mail.Send.Shared
    • Mail.ReadWrite.Shared (only if you expect to send attachments larger than 3 MB from WordPress).
  • 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)

Step 4 - 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 5 - Enable Sending emails with Microsoft Graph.

Perform the following steps to enable the plugin to send emails with Microsoft Graph.

  • Navigate to WP Admin > WPO365 > Mail.
  • Operate the toggle to Enable sending emails with Microsoft Graph.

Step 6 - Update the plugin's Azure AD registration

Perform the following steps to configure the Azure AD registration for the WPO365 plugin. 

  • Go to WP Admin > WPO365 > Mail. Every time this page loads, it will check whether the plugin has already been configured either with delegated or with application-level permissions. The plugin's Mail configuration page will become editable as soon as the check is completed.
  • To complete the mail authorization configuration, you must now supply the Directory (tenant) ID, Application (client) ID, Application (client) secret and the Redirect URI 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. The Redirect URI is already filled out and under normal circumstances does not need to be updated.

Please note The plugin may try to automatically check if it can find an existing configuration using the configuration you just entered. Most likely, it won't find any configuration and you should ignore this behavior and simply continue with the next step.

Step 7 - Configure a Microsoft 365 mailbox / user account

Perform the following steps to configure a Microsoft 365 mailbox / user account.

  • Navigate to WP Admin > WPO365 > Mail.
  • Enter a valid Microsoft 365 user account with enable mailbox as the Default "From" address (send mail as).

Step 8 - Authorize / Connect to Microsoft Graph

Perform the following steps to authorize the plugin to send WordPress email as the user whose account you entered in the previous step.

  • Navigate to WP Admin > WPO365 > Mail.
  • Click the Authorize button to right of the Default "From" address (send mail as) input field. This will bring up a dialog. Confirm by clicking Authorize again.
  • This will redirect your browser to login.microsoftonline.com and you are asked to authenticate as the user whose account you entered in the previous step.
  • After you authenticated successfully, your browser will be redirected back to your WordPress website and eventually the plugin's configuration page will be loaded. If you have previously registered the WordPress application successfully in Azure AD then the authorization should have been successful. 

Please note

  • If authorization was successful, you see Authorized! to the right of the Authorize button. 
  • If you want to delete an existing authorization object, then you can simply uncheck the corresponding option e.g. Delegated permissions.
  • You can re-authorize any time you want (but under normal circumstances there is no need to repeat the authorization because the plugin will refresh the authorization automatically using a so-called refresh token).

Step 9 - Send Test Email to validate the configuration

Perform the following steps to validate the configuration and send a test email.

  • 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.

Next steps: Adding premium features

You can unlock 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 | LOGIN or WPO365 | MS GRAPH MAILER plugin.

Configuring premium features

Sending attachments larger than 3 MB

A premium feature that is enabled by default is support for  sending attachments larger than 3 MB from WordPress. To actual send large attachments, the plugin will first create a draft email and then upload one or more (large) attachments. For the plugin to be able to do this, you must update the API Permissions for your App registration in Azure AD and you must add Microsoft Graph > delegated > Mail.ReadWrite permissions (and confirm by clicking Grant admin consent for ...). Alternatively, you can add Microsoft Graph > application > Mail.ReadWrite permissions, but this is not recommended.

Sending emails as / on behalf of another Microsoft 365 User Mailbox or Distribution List.

You can choose to send emails as / on behalf of another Microsoft 365 User Mailbox or Distribution List instead. If you select this option, the Default "From" address (User Mailbox) must have received delegated permissions for the other Microsoft 365 User Mailbox or Distribution List. If delegation has not been configured, you will receive an error (when sending a test email) informing you that The mailbox is either inactive, soft-deleted, or is hosted on-premise. If you receive this error, then please refer to this Microsoft article (to manage permissions for recipients) or this Microsoft article (for groups such as a Distribution List).

Please note that you cannot select the option to send as / on behalf of and to send from a Shared Mail Box at the same time.

Send emails from a Microsoft 365 Shared Mail Box

You can choose to send emails from a  Microsoft 365 Shared Mailbox instead. If you select this option, the Default "From" address (mail account) must be one of the users that has access to the Shared Mailbox. Also, if you configured delegated permissions, you must update the API Permissions for your App registration in Azure AD and you must add Microsoft Graph > delegated > Mail.Send.Shared permissions (and confirm by clicking Grand admin consent for ...). If you expect to send large attachments from a Shared Mailbox then you must also add Microsoft Graph > delegated > Mail.ReadWrite.Shared permissions. If you configured application-level Mail.Send permissions then you will find that you can already sent email as any user from a Shared Mailbox and do not need to add any new permissions.

Please note that you cannot select the option to  send as / on behalf of and to send from a Shared Mail Box at the same time.

Store Azure AD related secrets in /wp-config.php

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 default "From" address

You can 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.

Send emails with a different reply-to address

You can send emails with a Reply-to address that is different from the address sending the email.

Send to BCC

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.

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

First of all, please make sure that you have deactivated other plugins capable of sending WordPress emails such as WP Mail SMTP or Mail Integration for Office 365 / Outlook. Some plugins overwrite the WordPress internal function wp_mail() and doing so will prevent the WPO365 Microsoft Graph Mailer for WordPress to malfunction.

If the test email was not sent successfully, then please first check if the plugin has detected an error, as shown below.

Also, if an error occurred, then the plugin may have generated a WPO365 health message to inform you about it. To see the latest health messages, if may be needed to refresh the page.

Last but not least, you may check the plugin's debug-log for any errors. Please perform the following steps to collect debug information:

  • Navigate to WP Admin > WPO365 > ... > Debug and check Enable debug.
  • Reproduce the error.
  • Navigate back to the Debug tab as soon as possible thereafter, click Download as JSON and send it to our support team (in a separate file attachment).

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