---
title: "Send email with Microsoft (OAuth 2)"
slug: "send-email-with-microsoft-oauth-2"
tags: ["Developer", "How-to", "Site Administrator", "Totara Platform"]
updated: 2026-09-22T09:55:08Z
published: 2026-09-22T09:55:08Z
canonical: "totara.help/send-email-with-microsoft-oauth-2"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://totara.help/llms.txt
> Use this file to discover all available pages before exploring further.

# Send email with Microsoft (OAuth 2)

If you wish to enable Microsoft OAuth 2 authentication for your email connection then you will need to enable the OAuth 2 plugin on your Totara site and go to the Microsoft developer console to configure authentication.

1. Go to the [Microsoft Azure portal](https://azure.microsoft.com/account/).
2. Click **New registration** under **App registrations**.
3. Give your app a name, e.g. 'Totara Email'.
4. Select the appropriate option for **Supported account types**. Either **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** or **Accounts in this organizational directory only (Single tenant)** may be used, depending on the organisation's Azure configuration.

> [!WARNING]
> Many organisations use a **Single tenant** configuration for security and organisational reasons. If **Single tenant** is selected, the endpoints configured later must reference the Tenant ID rather than **/common/** (see the note at step 25).
5. Choose **Web** for **Redirect URI**.
6. Add your site's URL appended with **/admin/oauth2callback.php** to the **Redirect URLs** section e.g. 'https://totaralearn.com/admin/oauth2callback.php'.
7. Click **Register**.
8. Take a note of the **Application (client) ID**.
9. Select **Authentication** from the side menu.
10. Ensure that the **Implicit grant** settings are disabled.
11. Select **API permissions** from the side menu.
12. Ensure that the **SMTP.Send** and **offline_access** permissions are available under **Microsoft Graph**, and if they are not then add them as delegated permissions.
13. Select **Certificates & secrets** from the side menu and click **New client secret**.
14. Add a description, e.g. your app name (Totara Email), and select when the password/secret will expire.
15. Copy the generated secret **Value** (not the Secret ID) for use in Totara.

## Recommended: create a Microsoft SMTP service

> [!WARNING]
> From Totara 18.7 onwards, the OAuth 2 issuers page includes a **Create new Microsoft SMTP service** button. This option is recommended because it creates the correct endpoints by default and configures the required scopes automatically. Only the Client ID and Client Secret need to be added. If this option is used, the manual custom service steps below are not required.

1. In Totara go to *Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details*.
2. Click **Create new Microsoft SMTP service**.
3. Enter the application ID from the Microsoft Azure portal as the **Client ID**, and the **Secret Value** copied in step 16 as the **Secret**.
4. Uncheck **Show on login page** (it is recommended that the email and login OAuth services are not mixed).
5. Click **Save changes**.
6. If the Azure app is configured as **Single tenant**, edit the endpoints created for this service and replace **/common/** in each endpoint URL with the Tenant ID (see the note at step 25). If the app is Multitenant, no change is required.

> [!WARNING]
> Once the Microsoft SMTP service is created and connected, continue from the **Connect to a system account** step below (step 27).

## Alternative: create a custom service manually

If the **Create new Microsoft SMTP service** option is not available (for example on sites earlier than Totara 18.7), a custom service can be created manually as follows.

1. In Totara go to *Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details*.
2. Click **Create a new custom service**.
3. Enter a name, e.g. 'Microsoft Email OAuth'.
4. Enter the **Secret Value** generated in the Microsoft Azure portal (copied in step 16) as the **Secret** and the application ID as the **Client ID**.
5. In **Scopes included in a login request** enter any value. This field is not used, but a value must be provided.
6. In **Scopes included in a login request for offline access** add the following: **https://outlook.office.com/SMTP.Send offline_access**
7. Uncheck **Show on login page** (it is recommended that you do not mix the email and login OAuth services).
8. Click **Save changes**.
9. Click the **Configure endpoints** icon for the new service.
10. Click **Create new endpoints**, then add the following:

| **Name** | **URL** |
| --- | --- |
| authorization_endpoint | [https://login.microsoftonline.com/common/oauth2/v2.0/authorize](https://login.microsoftonline.com/common/oauth2/v2.0/authorize) |
| token_endpoint | [https://login.microsoftonline.com/common/oauth2/v2.0/token](https://login.microsoftonline.com/common/oauth2/v2.0/token) |

> [!NOTE]
> If the Azure app is configured as **Single tenant**, the **/common/** segment in each endpoint URL must be replaced with the Tenant ID of the OAuth 2 app in Azure. For example, if the Tenant ID is **46314b30-b357-4da6-8f22-0184a12371c0**, the authorization_endpoint becomes:
> 
>   
> 
> **https://login.microsoftonline.com/46314b30-b357-4da6-8f22-0184a12371c0/oauth2/v2.0/authorize**
> 
>   
> 
> and the token_endpoint becomes:
> 
>   
> 
> **https://login.microsoftonline.com/46314b30-b357-4da6-8f22-0184a12371c0/oauth2/v2.0/token**
> 
>   
> 
> If the app is configured as Multitenant, the **/common/** endpoints above should be used unchanged. If a Single tenant app is used but the endpoints are not updated accordingly, the connection will not work.

## Connect the account and configure outgoing mail

1. Return to the OAuth 2 services page.
2. Click the **Connect to a system account** icon.
3. Click **Continue**.
4. Sign in with your Microsoft email account that is used for your Totara email service.
5. Accept the permissions in Microsoft.
6. Go to *Quick-access menu > Server > Email > Outgoing mail configuration*.
7. Change **SMTP Auth Type** to XOAUTH2.
8. Change **Oauth2 Service** and choose the OAuth service you just created.
9. Set **SMTP Username** to the email of the account used for sending email (this should be the same as the **No-reply address**, i.e. the email address of the user connected via OAuth).
10. Set **SMTP Password** to any random text. It must not be blank, but otherwise, it does not matter.
11. Click **Save changes**.

Join the [Totara Community](https://totara.community/) for more resources to help you get the most out of Totara.

© Copyright 2026 Totara Learning Solutions. All rights reserved.