Mail Configuration

Novantra sends email for a handful of important user flows. This guide explains what those flows are, and how the install gets the SMTP transport it uses to actually deliver them.

Where mail is used

The mail subsystem is the only way these things happen:

Password resets. A user requests a reset; they get a link by email.
Login unlock. After repeated failed logins, the account is temporarily locked. The unlock code is delivered by email.
Membership invitations. When an admin invites someone to an organization, the invite arrives by email.
Signup and onboarding codes. Cloud signup uses email-delivered one-time codes during account creation.
Admin email verification. When you create or change the email on an administrator account, the verification step happens by email.
Mail configuration tests. When you change SMTP settings, you can send yourself a test email from the settings page to confirm the transport works.

If mail breaks, these flows visibly stop working. Other parts of the product continue to function, but anything that requires an email round-trip becomes inaccessible until mail is restored.

Cloud vs Sovereign

Mail is configured at the install level, and there is one config per install. Where that config lives depends on which product you run:

	Cloud	Sovereign
Who owns the mail transport	Novantra	You
Per-tenant SMTP configuration	No - shared managed mailer	N/A - one config per install
Where you change settings	You don’t	`/admin/system/mailer` in the system console
Sender domain	Novantra-controlled	Yours

Cloud tenant admins: mail just works. You will not find a mail settings page in your workspace. Novantra runs a managed shared mailer for the SaaS product. The rest of this guide is for Sovereign operators. If you need a per-organization custom sender domain in Cloud, talk to your account team - that is a deferred capability.

Sovereign: configuring mail

Mail settings live in the system console under System → Mailer, and require the install-admin role (SystemConfigure permission). There is one config per install; all organizations on the install share it.

You can defer mail configuration during the first-run setup wizard, but several flows will stop working until you come back and finish it:

New install-admin accounts cannot complete email verification.
Membership invitations to new users will fail.
Password resets will fail.

So while it’s optional during install, it’s effectively required for normal operation.

Sender identity

Every send needs a “from” address. You configure that here:

Sender address (required) - the email address mail will appear to come from, for example novantra@acme.com.
Sender name (optional) - the display name people see in their inbox, for example Acme Novantra or Acme HR Platform.

Sender address must be a real, valid email address. There is no domain verification step inside Novantra (we don’t enforce SPF/DKIM ourselves - see What’s not included below), so the address you pick is whatever your SMTP transport will accept on the way out.

Pick a provider

There are four choices. Pick the one that matches the mail infrastructure you already have.

SMTP (generic)

Use this if you have an existing SMTP relay - a corporate Exchange, Postfix, a smarthost provided by your hosting platform, or anything that speaks plain SMTP.

Field	Default	Notes
Host	-	The SMTP server hostname or IP.
Port	`587`	Most providers accept 587 with STARTTLS. Use 465 if your provider requires implicit TLS.
Secure (TLS)	on	Leave on for STARTTLS or implicit TLS.
Username	-	Optional. Leave blank if your relay accepts unauthenticated traffic from your network.
Password	-	Optional, encrypted at rest.
Ignore TLS errors	off	Leave off in production. Only useful for internal test relays with self-signed certs.
Connection timeout	sensible default	Increase if your relay is slow to respond.

Microsoft 365

Use this if your organization uses Microsoft 365 and you want Novantra mail to flow through your tenant’s SMTP service.

Field	Default	Notes
Host	`smtp.office365.com`	Pre-filled.
Port	`587`	Pre-filled.
Username	-	Required. The full email address of the M365 account Novantra will send as.
Password	-	Required. App password or service account password. Encrypted at rest.

Microsoft 365 SMTP auth requires basic authentication (username + password) to be enabled on the account, often with an app password. OAuth2 to M365 is not supported by Novantra today. Check with your M365 admin before going down this path.

AWS SES

Use this if you send mail through Amazon Simple Email Service. Novantra connects to SES over its SMTP interface (not the API).

Field	Default	Notes
Region	-	Required. The AWS region your SES is set up in (e.g. `eu-west-1`).
Host	derived from region	Defaults to `email-smtp.<region>.amazonaws.com`. Override only for VPC endpoints.
Port	`587`	Pre-filled.
Username	-	Required. Your SMTP credential username from SES - not your AWS access key ID.
Password	-	Required. The SMTP credential password from SES. Encrypted at rest.

To create the credential pair, use the SES console’s SMTP settings screen, not regular IAM access keys.

Console (development only)

Use this for evaluation, local development, or staging where you do not want mail to actually be delivered. The “console” provider does not call out to any network - it logs the message metadata to the install’s log stream so you can see what would have been sent.

Do not use the console provider in production. Real user flows that depend on email (password reset, invitations, unlock codes) will appear to succeed but no email is sent.

Send a test email

Once you’ve saved a configuration, click Send test email on the same settings page. The test sends to the email address of the admin currently signed in.

The system records the outcome on the settings page:

When the last test was run.
Whether it succeeded or failed.
A sanitized error message if it failed (no raw SMTP banners, no leaked passwords).
The timestamp of the last successful real send (not just tests).
A running count of consecutive failures so you can spot a transport that recently broke.

You are rate-limited to 5 test sends per 15 minutes to prevent loops.

Day-to-day behavior

After setup, mail mostly takes care of itself. A few things to know:

Send failures do not block user actions inside the product. If SMTP is briefly down, the failed-send count rises, but a user clicking “reset my password” still gets a response - they just don’t get the email until you fix the transport.
Credentials are encrypted at rest with the install’s key provider (the one you configured in Sovereign Installation). Rotating SMTP passwords on your provider’s side requires editing the mailer config and saving the new password.
Every config change is audited. The “who changed it and when” record is kept in the install’s audit log.
Test failures do not affect production sends. A failed test means “this admin couldn’t get a test email”; the live send path uses the same config and may succeed or fail independently. Trust the last successful send timestamp and the consecutive failures counter as your real signal.

If you skip mail at install time

It’s allowed but limited. The first-run setup wizard lets you defer mail. If you do:

The first-admin account is created without email verification. You can verify it later, after mail is configured.
The setup wizard records that mail is pending.
User flows that depend on email will fail with a clear error until you finish.

Come back to System → Mailer in the admin shell when you’re ready.

What’s not included

These are explicit gaps in the current Sovereign mailer. They are tracked as future work; if any are blockers for you, raise them with your account team.

No DKIM signing. Your outbound mail is signed (or not) by whatever SMTP relay you point Novantra at. If you need DKIM, terminate DKIM on the relay.
No bounce or complaint feedback. AWS SES bounce callbacks, generic SMTP bounce parsing, complaint webhooks - none of that is wired into the product yet.
No per-organization SMTP. All organizations on one Sovereign install share the same mailer. Per-org sender domains and per-org transports are not configurable.
No OAuth2 auth. Only basic auth (username + password) is supported. This affects M365 modernization plans in particular.
No SendGrid, Mailgun, or Postmark API transports. Use their SMTP endpoints if you need them.
No advanced TLS controls. Beyond “use TLS” and “ignore TLS errors,” there’s no cert pinning or custom CA bundle.
Cloud per-tenant configuration. Cloud customers cannot bring their own SMTP today. The shared managed mailer is what’s available.

Sovereign Installation - the first-run setup wizard touches mail briefly; this guide picks up where that left off.
Access URLs - the mail subsystem builds links that point at your access URLs, so they need to be correct before mail is useful.