Configuring SMTP for sending emails

Contensis sends emails such as workflow notifications, form submissions, password resets, and other system messages through an SMTP server that you configure. This guide explains each of the SMTP settings, how they work together, and the most common configurations.

All settings described here are found in the Management Console under Global Settings.

By default, Contensis is configured to send email through Zengenti's SMTP server (EmailSMTPHost is set to smtp.zengenti.com), with From addresses on the contensis.com domain, typically no-reply@contensis.com. This combination works out of the box: contensis.com authorises Zengenti's mail servers, so the emails pass the sender checks (SPF/DMARC) that receiving mail servers perform.

That authorisation is also why you can't simply change the From address to your own domain. If you set a notification's From address to an address on your own domain (e.g. cms@example.com) while still sending through Zengenti's server, receiving mail servers will see email claiming to be from your domain but sent from servers your domain hasn't authorised. The messages will fail SPF and DMARC checks, and most providers, including Google and Microsoft, will quarantine or reject them. Your notifications may simply never arrive.

To send emails from your own domain, configure Contensis to use your own SMTP server by changing EmailSMTPHost and the related settings described in this guide. For example:

• If your organisation uses Microsoft 365, point Contensis at smtp.office365.com with OAuth2 authentication. See Setting up OAuth2 SMTP authentication for Microsoft 365.
• Otherwise, use your own mail server or a transactional email service that provides SMTP access, with the appropriate encryption and authentication settings below.

If you don't need emails to come from your own domain, you can leave the default configuration in place.

There are two independent decisions to make when configuring SMTP:

1. How to connect: the host, port, and whether the connection is encrypted.
2. How to authenticate: anonymously, with a username and password, or with OAuth2.

The settings for each are described below, followed by a full settings reference and common configurations.

Two settings control whether the connection to your SMTP server is encrypted, and how:

Notes:

• If both settings are true, EmailSmtpUseImplicitSSL takes precedence and implicit SSL is used.
• Contensis negotiates TLS 1.2 or TLS 1.3; older protocol versions are not supported. If your mail server only supports TLS 1.0/1.1 it will need to be updated.
• Make sure the port matches the encryption mode. The most common cause of connection failures is a mismatch, for example enabling EmailSmtpUseImplicitSSL while still pointing at port 587, or enabling STARTTLS against port 465.

Contensis chooses the authentication method in this order:

1. OAuth2: used if EmailSmtpUseOAuth2 is true.
2. Username and password (basic authentication): used if OAuth2 is off and both EmailSmtpUsername and EmailSmtpPassword are set.
3. Anonymous: if neither of the above applies, Contensis connects without authenticating. This is common for internal mail relays that allow sending from trusted IP addresses.

Set EmailSmtpUsername and EmailSmtpPassword to the credentials for your SMTP account. Both must be set. If either is empty, Contensis will attempt to send anonymously.

You should always combine basic authentication with one of the encryption modes above, otherwise your credentials are sent in plain text.

Note for Microsoft 365 customers: Microsoft has retired basic authentication for SMTP. Username/password authentication against smtp.office365.com no longer works, so you must use OAuth2 instead (see below).

Setting EmailSmtpUseOAuth2 to true switches SMTP authentication to OAuth2. Instead of a mailbox password, Contensis obtains a short-lived access token from your identity provider using the client credentials flow, and presents that token to the SMTP server.

OAuth2 requires an encrypted connection. If EmailSmtpUseOAuth2 is true but neither EmailSmtpUseSSL nor EmailSmtpUseImplicitSSL is enabled, sending will fail with an error.

OAuth2 works in one of two modes, decided by which settings you fill in:

If EmailSmtpOAuth2AzureTenantId is set, Contensis authenticates against Microsoft Entra ID for that tenant. This is the correct mode for Microsoft 365 / Exchange Online.

Required settings:

EmailSmtpOAuth2Scope can be left empty. It defaults to https://outlook.office365.com/.default, which is correct for Microsoft 365. EmailSmtpOAuth2TokenEndpoint is ignored in this mode.

Before Contensis can send email this way, an administrator must create an app registration in Microsoft Entra ID and grant it permission to send from your mailbox in Exchange Online. This is covered step by step in Setting up OAuth2 SMTP authentication for Microsoft 365.

If EmailSmtpOAuth2AzureTenantId is empty and EmailSmtpOAuth2TokenEndpoint is set, Contensis requests a token directly from that endpoint using the standard OAuth2 client credentials grant. Use this for non-Microsoft providers that support OAuth2 for SMTP.

Required settings:

If OAuth2 is enabled but neither EmailSmtpOAuth2AzureTenantId nor EmailSmtpOAuth2TokenEndpoint is set, sending fails with a configuration error.

When authenticating with OAuth2, the SMTP server still needs to know which mailbox is being used. Contensis uses:

• EmailSmtpUsername, if set (set this to the email address of the sending mailbox); or
• the From address of the email being sent, if EmailSmtpUsername is empty.

For Microsoft 365 this address must be a mailbox that your app registration has been granted permission to send from. If your emails go out from several different From addresses, each mailbox needs that permission, or you can set EmailSmtpUsername to a single authorised mailbox to use for authentication.

Follow Setting up OAuth2 SMTP authentication for Microsoft 365 for the Entra ID and Exchange Online steps.

Only use an unencrypted, unauthenticated configuration with a relay on a trusted internal network that permits sending from your Contensis servers' IP addresses.

• "OAuth2 authentication requires TLS": EmailSmtpUseOAuth2 is true but neither SSL setting is enabled. Set EmailSmtpUseSSL to true (or EmailSmtpUseImplicitSSL for SSL-on-connect providers).
• "OAuth2 is enabled but neither EmailSmtpOAuth2AzureTenantId nor EmailSmtpOAuth2TokenEndpoint is configured": fill in the tenant ID (Microsoft 365) or the token endpoint (other providers).
• Connection fails or times out: check that the port matches the encryption mode (465 for implicit SSL, 587 for STARTTLS), that a firewall isn't blocking the port, and that your mail server supports TLS 1.2 or later.
• 535 5.7.3 Authentication unsuccessful (Microsoft 365): usually a permissions issue with the app registration or service principal, or permissions that haven't propagated yet. See the troubleshooting section of Setting up OAuth2 SMTP authentication for Microsoft 365.
• "Cannot determine OAuth2 username": OAuth2 is enabled, EmailSmtpUsername is empty, and the email has no From address. Set EmailSmtpUsername to the sending mailbox's address.