#Overview

Custom Email Provider is a premium feature that allows developers to configure the sender of Magic Link emails by routing emails through their own SMTP servers. Emails sent from our servers come from the default noreply@trymagic.com.

Enabling a custom SMTP gives you full control over where your application's login emails are sent from, as well as the name of the sender. Custom email providers are configured at the application level by visiting the Settings section of the Dashboard.

#Configuration

Once Custom Email Provider has been unlocked for your workspace, you can configure your own custom SMTP server.

Refer to your SMTP provider to determine whether to use Basic Auth or OAuth.

#Basic Auth

• Sender email: The email address your app's login emails will be sent from. E.g. example@your-domain.com
  • ⁠Note: Do not to use your dashboard user account email as the Sender Email, or try to login with the Sender Email
• Sender name (optional): The name that appears on the subject line of the login email. Defaults to sender email address if not provided.
• Host: Hostname for your SMTP server. E.g. smtp.postmarkapp.com
• Port: Port of your SMTP server
• Username, Password: Credentials to authenticate into your SMTP server

#OAuth

• Sender email: The email address your app's login emails will be sent from. E.g. example@your-domain.com
  • ⁠Note: Do not to use your dashboard user account email as the Sender Email, or try to login with the Sender Email
• Sender name (optional): The name that appears on the subject line of the login email. Defaults to sender email address if not provided.
• Provider: OAuth Provider. E.g. Microsoft
• Client ID: The Client ID of your provider’s OAuth App
• Client Secret: The Client Secret of your provider’s OAuth App
• Tenant ID: Your Microsoft Tenant ID⁠
  • Note: This field is requried because, currently, only the Microsoft provider is supported

How to Set Up the Microsoft OAuth Provider

1. Log in to the Microsoft Azure portal
   • Use your organization credentials to access the Microsoft Azure registration portal. Refer to the official Microsoft documentation for more details.
2. Register a new application
   • Provide an application name
   • Select the supported account type
   • Enter the redirect URL (optional)
   • Click Register
3. Copy the Client ID
4. Create a Client Secret
   • In Microsoft Azure, go to Manage -> Certificates & secrets
   • Click New client secret
   • Provide a description and set an experation period
   • Select Add
   • Copy the Secret value
5. Enable the SMTP.SendAsApp permission
   • In Microsoft Azure, go to Manage -> API Permissions
   • Select Add a permission
   • Choose the APIs my organization uses tile
   • Select Office 365 Exchange Online
   • Choose Application permissions
   • In the Select permissions field, search for SMTP.SendAsApp
   • Check the box for SMTP.SendAsApp
   • Click Add permissions
   • Select Grant admin consent for <your organization name>, then click Yes to confirm
6. Register service principals in Microsoft Exchange using PowerShell
   • Run the following commands
     Powershell

     Copy

     01Install-Module -Name ExchangeOnlineManagement

     02⁠Import-module ExchangeOnlineManagement

     03Connect-ExchangeOnline -Organization <YOUR_TENANT_ID>

     ⁠For more information, see Authenticate SMTP connection using OAuth
   • Register the service principal of a Microsoft Entra ID application by running the following command
     Powershell

     Copy

     01New-ServicePrincipal -AppId <YOUR_APPLICATION_ID> -ObjectId <YOUR_OBJECT_ID>

     Important: To obtain the YOUR_APPLICATION_ID value, navigate to Overview -> Managed applications in local directory and copy the Object ID. 

With the above pieces of information, we will be able to create a TLS-encrypted context to route our Magic Link emails to your server.

#Send a test email

The Send test email button will be enabled after saving a valid custom SMTP configuration. It will attempt to send a test email from the specified custom SMTP configuration to the email of the Magic Dashboard user who is currently logged in.

If you do not receive your test email within 1-2 minutes, please check your configuration settings and try again.

If you run into any issues during setup, please reach out via our help widget in the bottom-right corner of this page.