SMTP settings

CxReports uses SMTP (or Microsoft Graph as an SMTP-equivalent transport) to send report emails — both ad-hoc emails from a report and scheduled deliveries from Report Generation Jobs.

There are two ways to configure outbound mail:

• Per-workspace, via the UI (preferred). A workspace admin adds one or more SMTP servers under Connections → SMTP Settings. Each workspace controls its own credentials, From addresses, and throttling. This is the recommended approach for almost all installations.
• Globally, via appsettings.json. A single SmtpServer block is defined at the application level and shared across every workspace on the instance. Useful when one operations team owns mail delivery for the whole installation, or when you want a default that does not require workspace admins to configure anything.

When both are present, the per-workspace UI configuration takes precedence for that workspace.

Configuring SMTP via the UI (preferred)

Navigate to Workspace Configuration → Connections → SMTP Settings and click + Add. The Configure SMTP Server dialog opens.

Common fields

Field	Notes
Name	Display name for this SMTP server. Required. Shown when picking a server in email-related settings.
Authentication Type	Basic or Microsoft Graph. See the two sections below. Required.

Authentication Type: Basic

Classic SMTP username/password authentication. Use this for self-hosted mail servers, Gmail SMTP, and any provider that still supports SMTP AUTH.

Field	Notes
Host	SMTP server address — e.g. smtp.office365.com, smtp.gmail.com, smtp.server.com.
Port	Common ports are 25, 465 (SSL), or 587 (TLS/STARTTLS).
Username	Usually your email address or account name.
Password	Account password or, for providers that require it, an app-specific password.
Use SSL	Enable for secure connections. Recommended whenever the server supports it.

Warning

Microsoft is deprecating Basic Authentication for SMTP. If you are using Microsoft 365 / Exchange Online, switch to Microsoft Graph below.

Authentication Type: Microsoft Graph

Sends mail through the Microsoft Graph API with app-only (OAuth 2.0) authentication. This is Microsoft's recommended approach for Microsoft 365 / Exchange Online.

Field	Notes
OAuth Tenant ID	Azure AD tenant ID. Find it in Azure Portal → Azure Active Directory → Overview.
OAuth Client ID	Application (client) ID from your Azure AD app registration.
OAuth Client Secret	Secret value created in your app registration under Certificates & secrets.

Azure AD setup required

1. Register an app in Azure AD (App registrations).
2. Add the API permission Mail.Send (Application type).
3. Grant admin consent for the permission.
4. Create a client secret and copy the value into the OAuth Client Secret field.

The From Address configured below must be a valid mailbox in your Microsoft 365 tenant — Microsoft Graph rejects sends from addresses that do not exist.

Throttling

Optional. When enabled, CxReports rate-limits outbound mail so the upstream server is not flooded — important for shared SMTP relays and providers with per-minute send caps.

Field	Notes
Use Throttling	Toggle to enable throttling.
Emails per Interval	Maximum number of emails sent during one interval. Default 50.
Throttle Interval	Length of one interval — e.g. 1 minute.

From addresses

A list of Display Name / Address pairs the workspace can send from. Click + Add to add a row, fill in the display name and email address, and save.

When a report or job sends an email, the user picks one of these From addresses. Configuring at least one is required for the SMTP server to be usable.

For Microsoft Graph, each address must correspond to a real mailbox in the tenant.

Test Connection

Click Test Connection at the bottom of the dialog to verify the configuration end-to-end. CxReports authenticates against the configured server (or Microsoft Graph) and reports any error inline.

Configuring SMTP via appsettings.json

Define a global SmtpServer block in appsettings.Production.json. The block applies to every workspace on the instance unless that workspace has its own UI-configured SMTP server, which takes precedence.

{
  "SmtpServer": {
    "From": "[email protected]",
    "ReplyTo": "[email protected]",
    "Host": "localhost",
    "Port": 1025,
    "Username": "",
    "Password": "",
    "EnableSsl": false,
    "Throttling": {
      "MaxEmailsPerInterval": 2,
      "ThrottleInterval": 1
    }
  }
}

Field	Notes
From	Default From address used when sending.
ReplyTo	Default Reply-To address.
Host	SMTP server address.
Port	SMTP port — typically 25, 465, or 587.
Username / Password	Credentials for SMTP AUTH. Leave empty for unauthenticated servers.
EnableSsl	true for SSL/TLS connections.
Throttling.MaxEmailsPerInterval	Maximum emails per throttle interval. Omit the whole Throttling block to disable throttling.
Throttling.ThrottleInterval	Throttle interval length, in seconds.

The global SmtpServer configuration only supports Basic SMTP authentication. To use Microsoft Graph, configure SMTP per workspace in the UI.

For the full list of application-level settings, see the appsettings.json reference.