Email Settings
The Email Settings page shows the active mail provider, live delivery status counters, and a test-send tool. Email powers user invitations, password reset notifications, and any notification workflow actions that target an email channel.
Note: Email provider selection and credentials are configured in the Tagnet Admin Console on the server, not in this page. This page is a read-only status view with a test-send tool.
Accessing the page
Open the Email tab of the System page. The page requires the Manage Settings permission, which is granted to the Admin role by default.
Delivery status
The top panel shows a real-time snapshot of outbox health:
| Counter | What it counts |
|---|---|
| Pending | Messages in flight or waiting for a retry. A non-zero Pending count that doesn't clear over time may indicate a provider connectivity problem. |
| Sent (24h) | Messages successfully delivered in the last 24 hours. |
| Failed (24h) | Messages that failed or were dead-lettered in the last 24 hours. Any value above zero turns this counter red. |
The status chip in the top-right corner summarizes the three counters:
| Chip | What it means |
|---|---|
| Not configured | No mail provider is active (Mail:Provider=None). Invitations and password resets cannot be delivered by email. |
| Healthy | Provider is active and no failures recorded in the last 24 hours. |
| Failing | One or more messages failed or were dead-lettered in the last 24 hours. |
For a full per-message view with retry controls, see Email Delivery.
Provider configuration
The provider panel shows the currently active provider and sender identity:
| Field | Description |
|---|---|
| Active provider | Which mail backend is in use: Dev, SMTP, SendGrid, Azure Communication Services, or Not configured. |
| Mode | Customer (on-premises, admin-configured) or Platform (hosted Tagnet, managed by the platform). |
| From address | The envelope sender for all outgoing messages. |
| From display name | The friendly display name shown alongside the From address in recipients' inboxes. |
Available providers
| Provider | When to use |
|---|---|
| Dev (pickup folder) | Development and testing only. Writes .eml files to a local directory instead of sending. Never use in production. |
| SMTP | Connect to any SMTP relay: Office 365, Google Workspace, on-premises Exchange, or a local relay. Supports STARTTLS (port 587) and implicit TLS (port 465). |
| SendGrid | Requires a SendGrid account and an API key with Mail Send permission. Good option for cloud-hosted deployments without an existing mail infrastructure. |
| Azure Communication Services | Recommended for Azure-hosted Tagnet deployments. Uses an ACS resource in the same Azure subscription. The connection string is encrypted at rest. |
Note: SMTP passwords, SendGrid API keys, and ACS connection strings are encrypted at rest using ASP.NET Data Protection when written through the Admin Console.
Hosted Tagnet (Platform mode)
When Tagnet is running as a hosted instance, the provider banner reads "Managed by the Tagnet platform." Email delivery is configured by the platform; the From address and provider cannot be changed from this page. Test send remains available so administrators can verify that the platform connection is working.
Send test email
Use this section to verify that the configured provider is working end-to-end without waiting for a real transactional email to fire.
- Enter a recipient address in the Recipient address field.
- Click Send.
The test email renders through the same branded template pipeline as real transactional emails. You are validating the actual output, not a simplified plain-text substitute. A successful send reports the delivery time in milliseconds and the provider's message ID (when available). A failed send shows the error message from the provider.
Note: The test send goes directly through the active provider and bypasses the outbox queue. A successful test does not create an outbox row, but the delivery status counters refresh after the send completes.
The Send button is disabled when no provider is configured (Mail:Provider=None).
Configuring email (Admin Console)
Email settings are changed on the Email Setup page in the Tagnet Admin Console, on the server, not in this page. Open the Admin Console and select Email in the left navigation, under Web Server.
The page shows what is currently configured, then lets you choose a provider and its connection details:
-
Choose a provider. Pick None, SMTP, SendGrid, or Azure Communication Services. None disables email delivery entirely: invitations and password resets fall back to showing their link in the admin UI instead of sending it.
-
Set the From address and, optionally, a display name. Required for every provider except None.
-
Fill in the provider's connection details.
- SMTP: host, port (587 by default), Use TLS, an optional username, and a password.
- SendGrid: an API key with Mail Send permission.
- Azure Communication Services: the resource's connection string.
A secret you have already saved is never shown back to you. A caption under the field says one is stored, and you can leave the box blank to keep it, or type a new value to replace it. For the SMTP password you can also click remove it in the caption to delete the stored password when you save, for example when moving to a relay that needs no sign-in.
-
Click Test. For SMTP, this opens a real connection to the server and runs three checks (Connectivity, TLS, Authentication) without sending a message: STARTTLS on port 587, implicit TLS on port 465, and a warning if TLS is off entirely. SendGrid and Azure Communication Services only get a format check, since testing them for real means sending mail, which the test-send tool on this page already does after you save.
-
Click Save and restart. The page re-runs the checks first and aborts without saving if any of them fail, so a broken configuration never reaches the service. Once the checks pass, it writes the
Mail:*settings (secrets encrypted at rest) and restarts the Tagnet service.
Note: Changing the Admin Console configuration and restarting the service is not the same as confirming delivery. Once the service has restarted, come back to the Email tab of the System page in the web app and use the test-send tool above to send a real message through the new provider.
Choosing an inactive provider's radio button does not clear the values stored for the providers you are not using. Only the active provider's settings are written when you save.
The Email Setup page requires the Admin Console to run as administrator, since it writes appsettings.Production.json and restarts the Windows service. If it isn't elevated, click Restart as administrator.
Tip: The
Mail:*rows still appear on the Admin Console's App Settings page, but they are read-only there with a Manage in Email Setup hint. Use the Email Setup page to change them.
Troubleshooting
The page shows "Not configured"
The Mail:Provider setting is None (or missing). Open the Admin Console, go to Email in the left navigation, choose a provider, and save. Until email is configured, invitations and password resets cannot be delivered by email, and the Users page will show a warning banner.
Delivery status shows failures
One or more messages in the last 24 hours failed to deliver. Open Email Delivery to see individual failed rows, read the error message, and either retry or dead-letter them. Common causes:
- SMTP authentication failure: Check the username and password in the Admin Console. SMTP passwords stored before the DataProtection key rotation may need to be re-entered.
- SendGrid authorization error: Verify the API key has Mail Send permission in the SendGrid dashboard.
- ACS connection string invalid: Re-enter the connection string from the Azure portal. Confirm the ACS resource is in an active state and the linked email domain is verified.
- From address not verified: For SendGrid and some SMTP relays, the From address must be verified by the provider. Check the provider's dashboard for sender verification status.
Test send succeeds but recipients aren't receiving invitation emails
The test send bypasses the outbox queue and goes directly to the provider. If the test succeeds but workflow or invitation emails are not arriving, check Email Delivery for failed rows and read the per-row error messages. The issue is likely the outbox consumer encountering a provider error on a specific message type.
The "Send" button stays disabled after entering an address
The button requires a valid email address format. Confirm there are no extra spaces and that the address contains an @ and a domain. If the provider is None, the button is permanently disabled. Configure a provider first.