Setting up EMail SMTP with Microsoft 365

This document describes how to configure SMTP sending via OAuth 2.0 Client Credentials Flow with Microsoft Entra ID (formerly Azure AD) to send Emails from Simplifier via Microsoft Exchange

1. Overview

Many services now require modern authentication (OAuth 2.0) instead of basic username/password for SMTP. For Microsoft 365 (Exchange Online), this is done using:

An application registered in Microsoft Entra ID
OAuth 2.0 Client Credentials Flow (app-only authentication)
The SMTP.SendAsApp permission in “Office 365 Exchange Online”
Simplifier Administration Rights

Within Simplifier you need the:

Tenant ID
Client ID (Application ID)
Client Secret

to obtain an access token and authenticate to the Microsoft 365 SMTP serve using OAuth

2. Prerequisites

A Microsoft 365 tenant with Exchange Online
Admin access to Microsoft Entra ID
Admin / configuration access to your Simplifier Server Settings
PowerShell with Exchange Online Management module installed (for creating the service principal and mailbox permissions)

3. Register the Application in Microsoft Entra ID

1. Go to the Entra ID admin center: https://entra.microsoft.com and log in to your tenant.
2. Navigate to: Identity → Applications → App registrations → New registration
3. Configure the app:
  Name: any recognizable name (e.g., SMTP OAuth Simplifier).
  Supported account types: leave default (Single tenant) unless you have special needs.
  Redirect URI: not required for client credentials; default can be retained.
4. Click Register.

You now have an application with an Application (client) ID and associated Directory (tenant) ID.

4. Create a Client Secret

1. Open the registered app
2. Go to Certificates & secrets → New client secret
  Enter:
  Description: e.g., SMTP Client Secret.
  Expires: choose an appropriate lifetime (e.g., 24 months)
3. Click Add and immediately copy the value of the client secret.

You only need the Value (client secret key) for configuration in your application, not the Secret ID.

The secret value is visible only once; if you leave the page, you can’t see it again.

Note the expiration date and set a reminder to renew it before it expires to avoid SMTP interruptions

5.Assign SMTP Application Permissions

In the same app, go to API permissions
Click Add a permission
Select:
APIs my organization uses → search for Office 365 Exchange Online.
Choose Application permissions.
Find and select SMTP.SendAsApp.
Click Add permissions.
An Entra ID admin must Grant admin consent for these permissions.

This allows the app to send email via SMTP as an application (app-only).

6. Create a Service Principal and Grant Mailbox Access

To allow the app to send from a specific mailbox (for example invoices@example.com), you must:

1. Collect the following from the Entra ID portal:
  Tenant ID:
  Navigate to Identity → Overview and copy the tenant ID.
  Application ID (Client ID):
  From Applications → Enterprise applications → select your app → copy Application ID.
  Object ID (Service principal object ID):
  Important: use the Enterprise applications view, not the App registrations view, to get the correct object ID.
2. Open PowerShell (as admin) and install / import the Exchange Online module:
```
Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
```
3. Connect to Exchange Online:
```
Connect-ExchangeOnline -Organization
```
4. Create the service principal in Exchange Online:
```
New-ServicePrincipal -AppId  -ObjectId
```
5. Verify the service principal:
```
Get-ServicePrincipal | fl
```
6. Grant the service principal access to the mailbox that will send emails (e.g., invoices@example.com):
```
Add-MailboxPermission -Identity "invoices@example.com" -User  -AccessRights FullAccess
```

Now the application is allowed to send emails from that mailbox via app-only SMTP.

Setup SMTP Settings in Simpilfier

In Simplifier, SMTP OAuth with Entra ID is configured under Server Settings → SMTP Settings, using the Authentication: OAuth with Entra ID option which supports Client Credentials Flow.

1. Open Server Settings
2. In SMTP Settings, set the Properties likeGeneral SMTP:
  - Send E-Mails: enable
  - SMTP Host: smtp-mail.outlook.com (or your Exchange Online SMTP host)
  - SMTP Port: 587 for TLS
  - Authentication: select OAuth with Entra ID. This uses the Client-Credentials-Flow
  OAuth / Entra ID:
  - Tenant ID: your Microsoft tenant ID
  - Client ID: the Entra ID application (client) ID
  - Client Secret: the client secret created in the app registration
  Mail headers:
  - Sender E-Mail: default sender address, e.g. no-reply@company.com
  - Sender: display name (optionally with email)
  - Server allows UTF‑8: enable if your SMTP server supports UTF‑8 for email addresses and headers
  - Default Charset: choose your default character set (e.g., UTF-8)
  - Username: often the same as the email address if required