---
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:56:05Z
published: 2026-09-22T09:56:05Z
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.

Note: Microsoft OAuth 2 + SMTP authentication for email is only available from **Totara 18.7** onwards.

## Configure the app in the Microsoft Azure portal

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)** can be used. Many organisations use Single tenant for security and organisational reasons.Note: If **Single tenant** is selected, the OAuth 2 endpoints configured later in Totara must use the Tenant ID rather than **/common/** (see the Single tenant note in the endpoint configuration below).
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**. If Single tenant was selected, also take a note of the **Directory (tenant) 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. Copy the **Value** column, not the **Secret ID** — the value cannot be retrieved again once you navigate away from this page.

## Configure the OAuth 2 service in Totara (recommended)

From Totara 18.7 onwards, the OAuth 2 issuers page provides a **Create new Microsoft SMTP service** option. This option creates the correct endpoints and configures the required scopes automatically, so only the Client ID and Client Secret need to be added.

1. In Totara go to *Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details* and click **Create new Microsoft SMTP service**.
2. Enter a name, e.g. 'Microsoft Email OAuth'.
3. Enter the **Client ID** (the Application (client) ID from Azure) and the **Client secret** (the secret **Value** generated in Azure in the previous step, not the Secret ID).
4. Uncheck **Show on login page** (it is recommended that you do not mix the email and login OAuth services).
5. Click **Save changes**.

**Single tenant:** If the Azure app was registered as Single tenant, edit the endpoints for the service and replace **/common/** in each endpoint URL with the Directory (tenant) ID from Azure. For example:  
  
**https://login.microsoftonline.com/common/oauth2/v2.0/authorize**  
becomes  
**https://login.microsoftonline.com/46314b30-b357-4da6-8f22-0184a12371c0/oauth2/v2.0/authorize**

## Alternative: create a custom OAuth 2 service manually

If the **Create new Microsoft SMTP service** option is not available, a custom service can be configured manually. The endpoints and scopes must then be added by hand.

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 (not the Secret ID) 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) |

**Single tenant:** If the Azure app was registered as Single tenant, replace **/common/** in each endpoint URL above with the Directory (tenant) ID from Azure. For example, **https://login.microsoftonline.com/common/oauth2/v2.0/authorize** becomes **https://login.microsoftonline.com/46314b30-b357-4da6-8f22-0184a12371c0/oauth2/v2.0/authorize**. If the endpoints are not updated, authentication will fail.

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