RegScale provides support for integrating with customer email systems using SMTP. Email configuration is required to facilitate user registration workflows and for alerts throughout the system. Prior to setting up any Identity and Access Management, we strongly recommend configuring email first. Ensure you understand what your outbound SMTP service requires for authentication (if any) and how to configure it.
Configuration
In order to configure email, you must be an Administrator. To get started, click your name in the top right corner and select "Setup". Click the "Email" tab on the right side of the screen. Clicking the button should bring up the email form where you should complete the following fields:
Common Fields
- SMTP Reply Email Address - the "No Reply" email address you would like to use for system generated emails
- SMTP Email Address - the SMTP account you will use to authenticate to your email server
- RegScale Administrator Email Address - the email address where alerts should be sent to the RegScale system administrator
- Email SMTP Port - port where the SMTP server is listening (usually 587)
- SMTP Server - URL for the customer's SMTP server. If using Office 365, it is
smtp.office365.com
Authentication Method
- Enable SSL - Checkbox for whether or not the SMTP exchange is encrypted with TLS/SSL.
- Email Authentication Method - None, Basic, or OAuth - Choose which authentication method is used by the outbound SMTP server being used. See below for details on each configuration.
Authentication Option - None
This is the simplest authentication method. If the outbound SMTP server supports anonymous send, set the "Email Authentication Method" to "None". Emails will not be authenticated when sent. No other configuration is needed.
Authentication Option - Basic
The "Basic" authentication method means username and password. When the "Email Authentication Method" is set to "Basic", the email agent in RegScale authenticates to the outbound SMTP server using the "SMTP Email Address" and the "SMTP Email Password" as credentials.
SMTP Email Password - Password used for authenticating the "SMTP Email Address"
Authentication Option - OAuth
For providers such as Microsoft Office365 which do not support Basic Authentication, RegScale supports Open Authorizations (OAuth). Set the "Email Authentication Method" to "OAuth" and complete the following fields:
- OAuth Authority - URL where the RegScale email agent authenticates itself.
- OAuth Application ID - Id of the application registration in the email provider (see below for provider specific examples)
- OAuth Secret - "Secret" from the application registration in the email provider (see below for provider specific example)
- Enable SSL - Should be enabled to use OAuth authentication
Provider Specific Settings
Amazon Simple Email Service (SES)
New to version 4.3.0 and later, RegScale now supports Amazon SES for sending email from RegScale. The config generally works as described above, with the following differences:
- For the reply email, ensure you are using a domain that has a verified identity in AWS SES (NOTE: this step requires verifying the DNS with some CNAME values per the AWS instructions)
- Setup AWS SMTP Credentials
- Ensure you use the option for STARTTLS using port 587 (SSL box must be checked in RegScale)
- The SMTP Email address will be the SES identity and not a normal email address
Once configured, click "Email Test" to ensure AWS SES has been configured and is working correctly.
Microsoft Office365
In August of 2023, Microsoft ceased supporting basic authentication for outbound email over SMTP. Users of Microsoft Office365 should configure Open Authorizations (OAuth) for email authentication. Configuring an outbound account for OAuth authenticated SMTP email is complex. Refer to these references on how to set up the Azure and Exchange configurations to support this feature:
Authenticate an IMAP, POP, or SMTP application by using OAuth
Enable SMTP AUTH for specific mailboxes
Notes:
- Use "smtp-mail.outlook.com" as the "SMTP Server" in RegScale
- Use "587" as the "Email SMTP Port" in RegScale
- Use "https://login.microsoftonline.com/{tenant_id}" as the "OAuth Authority"
- Ensure the "SMTP Email Address" is for a fully licensed user with a mailbox in Office365 (not an alias)
- Ensure the "service principals" created in the "Register your Application" steps are registered in your Exchange settings
- Ensure the account used has "SMTP.SendAsApp" permission
Legacy Email Configuration (No TLS)
Some older email clients and legacy environments do not support the secure TLS option that is enabled by default in RegScale. To manually disable TLS, set the "EMAIL_NO_TLS" environment variables to "true".
Testing Email
On the email form, click the "Email Test" button to attempt to send an email. If successful, you will get a green alert noting that the email was successfully sent. If any errors occur, a red alert box will show providing additional details on the error(s). (NOTE: The email test will be sent to the system administrator email provided above. If the test was successful but you don't see the email, please check your spam filters and Junk folder to make sure it was not filtered/blocked)
Updated 9 months ago