{"id":12647,"date":"2026-08-28T14:42:51","date_gmt":"2026-08-28T20:42:51","guid":{"rendered":"https:\/\/www.mrc-productivity.com\/techblog\/?post_type=ht_kb&#038;p=12647"},"modified":"2026-08-28T15:34:42","modified_gmt":"2026-08-28T21:34:42","slug":"implementing-oauth2-for-outlook-smtp","status":"publish","type":"ht_kb","link":"https:\/\/www.mrc-productivity.com\/techblog\/?ht_kb=implementing-oauth2-for-outlook-smtp","title":{"rendered":"Implementing OAuth2 for Outlook SMTP"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Microsoft 365 \/ Exchange Online <a href=\"https:\/\/learn.microsoft.com\/en-us\/exchange\/clients-and-mobile-in-exchange-online\/deprecation-of-basic-authentication-exchange-online\" target=\"_blank\" rel=\"noreferrer noopener\">no longer supports<\/a> Basic Authentication for many tenants. For customers who use their Microsoft Exchange SMTP servers within m-Power to send emails, this tech blog post will be a step-by-step guide on using <strong>OAuth2 client credentials<\/strong> with SMTP <code>XOAUTH2<\/code> instead of a traditional password.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">1. Register an application in Azure<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Go your <a href=\"https:\/\/portal.azure.com\">Azure Portal<\/a>. <\/li>\n\n\n\n<li>Go to <strong>App registrations \u2192 New registration<\/strong>. Any name works, such as <em>m-Power Emails<\/em>. No redirect URI is needed.<\/li>\n\n\n\n<li>Note the <strong>Application (client) ID<\/strong> and <strong>Directory (tenant) ID<\/strong> from the application&#8217;s Overview page.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth2_SMTP_2.png\" alt=\"\"\/><\/figure>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Under <strong>Certificates &amp; secrets<\/strong>, create a <strong>client secret<\/strong> and copy its <em>value<\/em> immediately.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth_SMTP_1.png\" alt=\"\"\/><\/figure>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Under <strong>API permissions<\/strong>, choose <strong>Add a permission \u2192 APIs my organization uses \u2192 Office 365 Exchange Online<\/strong>.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth_SMTP_3.png\" alt=\"\"\/><\/figure>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Select <strong>Application permissions<\/strong> and then search for the <code>SMTP.SendAsApp<\/code> permission. Once found, check this option. <\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth2_SMTP_4.png\" alt=\"\"\/><\/figure>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Click <strong>Grant admin consent<\/strong> and then click <strong>Add Permission<\/strong>.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon\">If you also use m-Power&#8217;s Email Reader Template, the same app registration can hold both <code>SMTP.SendAsApp<\/code> for sending and <code>IMAP.AccessAsApp<\/code> for reading.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">2. Authorize the mailbox in Exchange Online<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Run the following commands once in Exchange Online PowerShell as an Exchange administrator.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># Register the app's service principal with Exchange\nNew-ServicePrincipal -AppId &lt;client-id&gt; -ObjectId &lt;enterprise-app-object-id&gt;\n\n# Allow the app to use the sending mailbox\nAdd-MailboxPermission -Identity \"automated@yourcompany.com\" `\n    -User &lt;enterprise-app-object-id&gt; -AccessRights FullAccess\n\n# SMTP AUTH must be enabled on the mailbox, even when using OAuth2\nSet-CASMailbox -Identity \"automated@yourcompany.com\" -SmtpClientAuthenticationDisabled $false<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The &lt;<em>enterprise-app-object-id<\/em>> is found under <strong>Enterprise applications<\/strong>, not App Registrations, for the application you created:<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth_SMTP_5.png\" alt=\"\"\/><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\">3. Configure m-Power<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In the m-Power interface, go to <strong>Admin \u2192 Messaging \u2192 Messaging Configuration<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Enter <strong><code>oauth2<\/code> <\/strong>in the <code>email_auth_type<\/code> property. The additional OAuth2 fields will appear automatically.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"\/techblog\/images\/oauth_SMTP_6.png\" alt=\"\"\/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">You can alternatively configure these settings directly from a text editor of your choosing, by going to this location:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><code>...\/m-power\/mrcjava\/job_streams\/messaging.properties<\/code><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong><code>email_auth_type<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter <code>oauth2<\/code>. This property enables OAuth2 authentication. When blank, m-Power uses the previous email authentication behavior.<\/li>\n\n\n\n<li><strong><code>email_server<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter <code>smtp.office365.com:587<\/code><\/li>\n\n\n\n<li><strong><code>email_user<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter the Microsoft 365 mailbox the system will send as, such as <code>automated@yourcompany.com<\/code>.<\/li>\n\n\n\n<li><strong><code>email_sender<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter the default &#8220;From Address&#8221;. This must be the mailbox above that was set for <strong><code>email_user<\/code><\/strong> or a different address that mailbox is permitted to send as.<\/li>\n\n\n\n<li><strong><code>email_oauth_tenant_id<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter the Directory (tenant) ID from Step 1.<\/li>\n\n\n\n<li><strong><code>email_oauth_client_id<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Enter the Application (client) ID from Step 1.<\/li>\n\n\n\n<li><strong><code>email_oauth_client_secret<\/code><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark><\/strong> \u2014 Enter the client secret value created back in Step 1.<\/li>\n\n\n\n<li><strong><code>email_oauth_client_secret_encrypt<\/code><\/strong><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark> \u2014 Default value is <code>false<\/code> . Enter <code>true<\/code> to store the secret encrypted, similar to <code>email_password_encrypt<\/code>.<\/li>\n\n\n\n<li><strong><code>email_oauth_scope<\/code><\/strong> \u2014 Optional. The default value is <code>https:\/\/outlook.office365.com\/.default<\/code><\/li>\n\n\n\n<li><strong><code>email_password<\/code><\/strong> \u2014 This value is ignored when OAuth2 is enabled and may be left as-is or blank.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><mark style=\"background-color:rgba(0, 0, 0, 0);color:#ff0000\" class=\"has-inline-color\">*<\/mark>&#8211; required.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">An example <code>messaging.properties<\/code> configuration is shown below:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>email_auth_type=oauth2\nemail_server=smtp.office365.com:587\nemail_user=automated@yourcompany.com\nemail_sender=automated@yourcompany.com\nemail_oauth_tenant_id=00000000-0000-0000-0000-000000000000\nemail_oauth_client_id=11111111-1111-1111-1111-111111111111\nemail_oauth_client_secret=xxxxxxxxxxxxxxxxxxxxxxxx\nemail_oauth_client_secret_encrypt=false<\/code><\/pre>\n\n\n\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon\">No Tomcat restart is required. The messaging configuration is re-read when the file changes.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">How it works<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>m-Power requests an access token from <code>https:\/\/login.microsoftonline.com\/&lt;tenant&gt;\/oauth2\/v2.0\/token<\/code> using the client credentials grant, then authenticates to SMTP with <code>AUTH XOAUTH2<\/code> as the configured <code>email_user<\/code>.<\/li>\n\n\n\n<li>Tokens are cached and refreshed automatically about five minutes before they expire, so bulk task runs do not repeatedly call the token endpoint.<\/li>\n\n\n\n<li>The OAuth2 setting is system-wide and applies to every email m-Power sends, including scheduled tasks and message queues, workflow email actions, emailed reports such as HTML, PDF, and Excel output, analytics emails, verification codes, and task-failure notifications.<\/li>\n\n\n\n<li>Additional JavaMail settings can still be supplied through <code>email_other<\/code> using the <code>name:value;name:value<\/code> format. These settings take precedence.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Troubleshooting<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In the event the following Azure error codes are thrown, here is an explanation and solution for those codes.<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><tbody><tr><td><strong>Error<\/strong><\/td><td><strong>Solution<\/strong><\/td><\/tr><tr><td>Log:\u00a0<em>failed to obtain OAuth2 access token<\/em>\u00a0with\u00a0<code>AADSTS7000215<\/code><\/td><td>Invalid client secret (or the secret has expired). Check the secret expiration date in your Azure Portal.<\/td><\/tr><tr><td>Log:\u00a0<code>AADSTS500011<\/code>\u00a0\/\u00a0<code>AADSTS65001<\/code><\/td><td><code>SMTP.SendAsApp<\/code>\u00a0permission is missing from the app registration or Admin Consent was not granted.<\/td><\/tr><tr><td>SMTP error\u00a0<code>535 5.7.3 Authentication unsuccessful<\/code><\/td><td>Service principal not registered in Exchange, mailbox permission missing, or SMTP AUTH disabled on the mailbox \/ tenant.<\/td><\/tr><tr><td>Emails route to the plain (unauthenticated) sender<\/td><td><code>email_auth_type<\/code> property\u00a0in m-power&#8217;s messaging.properties is blank or misspelled; the value must be\u00a0<code>oauth2<\/code>.<\/td><\/tr><\/tbody><\/table><\/figure>\n","protected":false},"excerpt":{"rendered":"<p>Microsoft 365 \/ Exchange Online no longer supports Basic Authentication for many tenants. For customers who use their Microsoft Exchange SMTP servers within m-Power to send emails, this tech blog post will be a step-by-step guide on using OAuth2 client credentials with SMTP XOAUTH2 instead of a traditional password. 1&#8230;.<\/p>\n","protected":false},"author":12,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"footnotes":""},"ht-kb-category":[],"ht-kb-tag":[],"class_list":["post-12647","ht_kb","type-ht_kb","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/ht-kb\/12647","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/users\/12"}],"replies":[{"embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=12647"}],"version-history":[{"count":11,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/ht-kb\/12647\/revisions"}],"predecessor-version":[{"id":12662,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=\/wp\/v2\/ht-kb\/12647\/revisions\/12662"}],"wp:attachment":[{"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=12647"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=%2Fwp%2Fv2%2Fht-kb-category&post=12647"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/techblog\/index.php?rest_route=%2Fwp%2Fv2%2Fht-kb-tag&post=12647"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}