16.1Configuring the email provider

The email provider is the service the platform uses to send mail. Exactly one provider is active at a time. You can store settings for more than one provider, but only the active one sends mail.

Who can configure the provider

Email provider settings contain sending credentials, so they are restricted to system scope: your active role must be System Admin, and you also need the notifications:manage permission (System Admin holds every permission). Anyone else who tries to read or change the provider settings, including through the REST API, is refused with "Only the system administrator can manage email providers."

The three providers

Each provider is shown as a card at the top of the page. A card carries an Active badge when that provider is the one sending mail, or a Configured badge when its settings are stored but it is not active. The page header also shows a chip such as "SMTP active", or "No active provider".

When you open the page, it opens on the provider that is currently active.

Saving is switching

The page has a single Save button whose label tells you what it will do:

• When you are editing the provider that is already active, the button reads Save settings.
• When you select a different provider, the button reads Save & switch to followed by that provider's name (for example Save & switch to Microsoft Graph), and a notice appears, for example: "SMTP stays active until you save. Saving switches all outbound email to Microsoft Graph."

Saving a provider that is not active therefore also makes it the active provider. If the provider cannot be activated, an error message tells you why and the previous provider stays active.

Use Discard to throw away unsaved changes and reload the stored settings. The time the selected provider was last saved is shown beside the buttons as Last saved.

SMTP settings

To configure SMTP:

1. 1Make sure your active role is System Admin.
2. 2Open Integrations > Email Provider.
3. 3Select the SMTP card.
4. 4Under Server, enter the Host and Port, and choose whether to Use SSL/TLS.
5. 5Under Authentication, enter the Username and Password.
6. 6Under Sender, enter the From address and Display name.
7. 7Select Save settings (or Save & switch to SMTP if another provider is active).

Microsoft Graph settings

Microsoft Graph sends mail through Exchange Online without SMTP. The page shows the prerequisites:

• A Microsoft Entra app registration with the Mail.Send application permission, and admin consent granted for it.
• A licensed Exchange Online mailbox to send from.

A stored client secret is never sent back to the browser. Once one is stored, the field is shown as held (dots, not editable). To change it, select Replace secret beside the field label and type the new secret.

To configure Microsoft Graph:

1. 1In Microsoft Entra, register an application, add the Mail.Send application permission, grant admin consent, and create a client secret.
2. 2In the console, with the System Admin role active, open Integrations > Email Provider.
3. 3Select the Microsoft Graph card.
4. 4Under App registration, enter the Tenant ID, Client (Application) ID and Client Secret.
5. 5Under Sender, enter the Sender address (licensed mailbox).
6. 6Select Save & switch to Microsoft Graph (or Save settings if it is already active).

Tip: The Mail.Send application permission lets the app send as any mailbox in the tenant. Consider restricting the app to the sender mailbox with an Exchange Online application access policy.

Google Workspace settings

Google Workspace sends mail through the Gmail API using a service account with domain-wide delegation. The page shows the prerequisites: a Google Cloud service account with the Gmail API enabled and a JSON key downloaded, and, in the Google Admin console, the service account's client ID added under Domain-wide delegation with the scope https://www.googleapis.com/auth/gmail.send.

To configure Google Workspace:

1. 1Create the service account and JSON key, and set up domain-wide delegation as described above.
2. 2In the console, with the System Admin role active, open Integrations > Email Provider.
3. 3Select the Google Workspace card.
4. 4Under Service account, paste the Service account JSON key.
5. 5Under Sender (delegated user), enter the Delegated user email and Display name.
6. 6Select Save & switch to Google Workspace (or Save settings).

Sending a test email

Once a provider is active, the bottom bar of the page shows Send a test email.

1. 1Type a recipient address in the box (for example recipient@example.com).
2. 2Select Send test.
3. 3The result appears in the bar: a green tick and a confirmation, or a red cross and the error the provider returned.
4. 4Select Send another to test again.

The test always uses the active provider, not the card you are viewing. If you have just changed settings, save them first.

Deactivating email delivery

To stop all outbound email, select Deactivate in the page header. The stored settings are kept, but no provider is active, so every notification and every account email (password reset, account setup) is skipped until you activate a provider again.

Delivery retries

If the provider fails with a temporary error, the platform retries the send. By default it makes up to 3 attempts, waiting about 2 seconds before the first retry and doubling the wait each time, up to 30 seconds. An administrator can change this in the server configuration under EmailNotifications:Retry (MaxAttempts, BaseDelaySeconds, UseExponentialBackoff, MaxDelaySeconds). Setting MaxAttempts to 1 turns retries off. The number of attempts each email took is shown in Notification History.