---
title: "Send email with Microsoft (OAuth 2)"
slug: "send-email-with-microsoft-oauth-2"
tags: ["Site Administrator", "Developer", "Totara Platform", "How-to"]
updated: 2026-09-22T09:55:35Z
published: 2026-09-22T09:55:35Z
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**. Multitenant configurations should select **Accounts in any organizational directory (Any Azure AD directory - Multitenant)**. Organisations that use a Single Tenant configuration should select **Accounts in this organizational directory only (Single tenant)** instead.

> [!NOTE]
> If Single Tenant is selected, the endpoint URLs added in a later step must be adjusted to include the Tenant ID (see step 25). If the Azure app is configured as Single Tenant but the endpoints are not updated in Totara accordingly, the connection will not work.
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** for use in Totara. Note that this is the **Value** of the secret, not the **Secret ID**.

> [!NOTE]
> From Totara 18.7 onwards, the OAuth 2 consumer details page includes a **Create new Microsoft SMTP service** button. Using this option is recommended because it creates the correct endpoints by default and configures the required scopes automatically. When this option is used, only the Client ID and Client Secret Value need to be added, and steps 20 to 22, 24 and 25 below are not required. If the **Create a new custom service** option is used instead, follow all of the steps below.

1. In Totara go to *Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details*.
2. Click **Create new Microsoft SMTP service** (recommended, available from Totara 18.7 onwards). Alternatively, click **Create a new custom service** to configure the service manually using the steps below.
3. Enter a name, e.g. 'Microsoft Email OAuth'.
4. Enter the password generated in the Microsoft Azure portal as the **Secret** and the application ID as the **Client ID**. The **Secret** must be the **Value** of the client secret created in Azure at step 15, not the **Secret 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 both endpoint URLs must be replaced with the Tenant ID of the OAuth 2 app. 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**

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.