Skip to content

Email and Notifications

Applies to: All subscriptions

Purpose

Configure mail transport and notification recipients. This subsystem gets more attention here than its size suggests because its failure mode is unusually bad: nothing errors, nothing is logged in the interface, and the symptom reaching support is "a user cannot log in".

Audience

System administrators, with the customer's messaging team for deliverability.

Prerequisites

  • Installation Guide complete
  • A mail transport available: an SMTP relay or a vendor mail service
  • A sender address the customer's domain policy permits

Steps

1. Choose the transport

Option Suits
SMTP relay Most on-premises and hybrid deployments; the customer's existing mail infrastructure
Vendor mail service Cloud deployments where a managed sending service is preferred

Either is fine. What matters is that messages are actually delivered to real mailboxes, not that the transport connects.

2. Configure the transport

See Environment Variables for the exact keys.

Item Guidance
Host and port From the customer's messaging team
Encryption Match the relay's expectation; a mismatch fails at handshake
Credentials If the relay requires authentication. Failures appear at send time, not at startup
Sender address Must pass the customer's domain sender policies

That third row explains why mail problems are found late: the application starts perfectly with wrong mail credentials, and the fault surfaces only when someone requests a password reset.

3. Get deliverability right

A message that is sent but lands in a spam folder is, operationally, a message that was not sent.

Requirement Why
Sender policy records permit the sending host Otherwise messages are rejected or filed as spam
Message signing configured Improves deliverability and authenticity
Domain policy alignment Some receivers reject outright without it
Sender address is a real, monitored mailbox Replies and bounces must reach someone
Sending host not on a block list Check before go-live, not after complaints

Work this with the customer's messaging team during preparation. It is a multi-day change in many organisations.

4. Decide who receives what

Notification Typical recipient Note
Password reset The user Non-negotiable. Without it, users are locked out
One-time codes The user Same
Account creation The user, copied to the administrator —
e-Way Bill expiry warnings Logistics or dispatch Set the horizon to the real dispatch lead time, or the alert arrives too late to act on
Write-back failures The integration owner Silence here means the ERP quietly falls out of step
Job failures The operations owner —
Compliance alerts The tax or finance team —

Use distribution lists, never individual mailboxes. An alert addressed to a person who has left the organisation is an alert nobody receives, and nobody notices that nobody is receiving it.

5. Set alert horizons to match reality

An e-Way Bill expiry alert is useful only if it arrives while there is still time to act. Set the horizon from the customer's actual dispatch and transport lead times, not from a default. Too short and the alert is noise arriving after the decision point; too long and it is ignored.

6. Test to a real mailbox

Trigger a password reset to a mailbox someone actually reads, and confirm it arrives in the inbox rather than the spam folder. A relay that accepts the message proves only that the relay accepted it.

Validation

Check Method Pass condition
Transport reachable Connect to the relay from the application host Connection succeeds. Test from this host, not a workstation
Authentication works Send a test message Accepted, not rejected
Password reset arrives Trigger a reset to a real mailbox Delivered, in the inbox
One-time code arrives Trigger a code Delivered within the code's validity period. A slow relay makes codes expire before they are read
Not filed as spam Check the inbox, not just "delivered" status In the inbox
Sender policy passes Inspect the received message's authentication results Passes
Recipients are lists Review the configured recipients Distribution lists, not individuals
Expiry alerts fire Create a bill nearing expiry in a test environment Alert arrives with time to act
Failure alerts fire Force a write-back failure in a test environment Alert reaches the integration owner
Bounces are monitored Send to an invalid address The bounce reaches a monitored mailbox

The one-time-code timing check matters more than it looks: a relay that takes four minutes to deliver a code with a five-minute validity produces an intermittent, unreproducible sign-in failure.

Troubleshooting

Symptom Cause Action
No emails at all, application otherwise healthy Mail misconfigured or the path blocked Test from the application host. This locks users out with no visible cause
Application starts fine but sending fails Mail credentials are validated at send time, not startup Trigger a real send to test
Messages accepted but never arrive Filtered as spam, or rejected silently downstream Check sender policy records and any block lists
Delivered to spam Sender policy or signing not configured Work with the customer's messaging team
One-time codes arrive too late to use Relay latency exceeds the code's validity Reduce relay latency, or extend the code lifetime deliberately
Users say they never received a reset Wrong address on the account, or a shared mailbox nobody reads Confirm the address; account activation depends on a person receiving it
Expiry alerts arrive too late Horizon shorter than the real dispatch lead time Set the horizon from actual lead times
Nobody notices write-back failures Alerts disabled, or addressed to a departed employee Enable alerts and address them to a distribution list
Alert volume ignored Horizons or thresholds too aggressive Tune to a level people act on. An ignored alert is worse than none
Emails link to the wrong environment Base URL wrong for this environment See Domains and URLs