Skip to main content

Configure external SMTP servers for Microsoft 365 using OAuth

Zuora

Configure external SMTP servers for Microsoft 365 using OAuth

  1. Last updated
  2. Save as PDF

This article describes how to configure the external SMTP server for Microsoft 365 using OAuth 2.0 authentication. After the configuration, Zuora sends emails to your customers using Microsoft’s SMTP server when email notifications are triggered.

Prerequisites

Before configuring the external SMTP server in Zuora, ensure that the following requirements are met:

  • Enable SMTP AUTH for the mailbox used to send emails in Microsoft 365.
  • If the email address of your Zuora tenant is different from the mailbox that has SMTP AUTH enabled in Microsoft 365, add a "Send as" permission for your Zuora tenant’s email in Microsoft 365.
  • The following permissions are added to your application in Azure Active Directory (Azure AD):
    • IMAP.AccessAsUser.All
    • SMTP.Send
    • offline_access
    For more information about managing permissions in Azure AD, see Request the permissions in the app registration portal.
  • Ensure that your Azure AD user account is only assigned to limited groups.
    The size of generated access tokens depends on the number of groups in this user account. If the token is too large, it might cause errors such as exceeding the size limitation on HTTP headers. For more information, see Groups overage claim in Microsoft’s documentation.

Procedure

Take the following steps to configure the external SMTP server for Microsoft 365 using OAuth 2.0 authentication:

  1. Create an OAuth 2.0 Provider using the Authentication Code grant type.
  2. Configure the external SMTP server settings for Microsoft 365.

Step 1: Create an OAuth 2.0 Provider using the Authentication Code grant type

  1. Navigate to Settings > Administration > Manage OAuth 2.0 Providers.
  2. Click New OAuth 2.0 Provider. The New OAuth 2.0 Provider page opens.
  3. Fill in the fields with the values in the following table:
    Field Value Note
    Name <provider name> Name of the provider.
    Grant Type Authorization Code  
    Client ID <client ID> Application ID of your application in Azure AD.
    Client Secret <client secret> Application secret of your application in Azure AD.
    Authorization EndPoint https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize <tenant> is your tenant ID in Azure AD instead of your tenant ID in Zuora.
    Access Token EndPoint https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token <tenant> is your tenant ID in Azure AD instead of your tenant ID in Zuora.
    Revoke EndPoint (leave blank)  
    Test EndPoint (leave blank)  
    Scope https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access  
    For more information about these fields, see Add an OAuth 2.0 Provider.
  4. Click Save. After the OAuth 2.0 provider is successfully created, you can find it on the All OAuth 2.0 Providers page.
  5. Click the name of the provider created in step 4 on the All OAuth 2.0 Providers page. The OAuth 2.0 Provider Details page opens.
  6. Click Obtain Token. After obtaining the access token successfully, you can find the access token and expiration date on the page.

For more information about OAuth 2.0 authentication in Azure AD, see Microsoft identity platform and OAuth 2.0 authorization code flow.

Step 2: Configure the external SMTP server settings for Microsoft 365

  1. Navigate to Settings > Administration > Manage SMTP Settings.
  2. Click Edit in the External SMTP Server Configuration Settings section.
  3. Fill in the fields with the values in the following table:
    Field Value Note
    SMTP Server Name smtp.office365.com  
    SMTP Port 587  
    SMTP Enable StartTLS true  
    Authentication OAuth 2.0  
    SMTP User Name <username>

    Username of the logged-in user in Azure AD when the OAuth access token is generated.

    Ensure that your Azure AD user account is only assigned to limited groups. Otherwise, the size of generated access tokens grows and might cause errors. For more information, see Prerequisites.
    OAuth2.0 Provider <oauth 2.0 provider> From the dropdown list, select the OAuth 2.0 provider created for Microsoft.
    SMTP SocketFactory Port (leave blank)  
    SMTP SocketFactory Class (leave blank)  
    SMTP SocketFactory Fallback (leave blank)  
    For more information about these fields, see External SMTP Configuration Fields.
  4. Click Test Connection And Save. The data is saved if the connection is successful.
    If an error occurs, it suggests that the configuration information is not valid and a corresponding error message appears. For more information about error messages and solutions, see Common error messages.
  5. Click Edit in the first section of the page.
  6. From the Deliver E-Mail Notifications Using list, select External SMTP Server.
  7. Click Save.