Email delivery and templates
DartRelay sends email for sign-in codes, password resets, new accounts and security alerts. This page explains how to connect it to your mail server, who receives which message, and how to reword, translate or switch off each one.
What DartRelay sends, and to whom
Every message has one of three audiences. The templates list shows each audience as a coloured label so you can see at a glance who a message reaches.
| Audience | Who receives it |
|---|---|
| The person | The user the message is about, at the email address on their account. |
| Administrators | Everyone on the Admin Notification Emails list in System → Settings. |
| The tenant | The notification addresses set on a tenant's address in Tenancy & Branding. This is the only message that goes to people outside your own organisation, so its label is green. |
The messages
| Message | Goes to | Sent when |
|---|---|---|
| New user welcome | The person | An administrator creates a portal account that has an email address. |
| Email one-time code | The person | Someone signing in needs an email code for two-factor authentication. |
| Password reset link | The person | Someone asks for a password reset on the sign-in page. |
| Password reset confirmation | The person | A password reset has succeeded. |
| Seat limit reached | Administrators | A launch is refused because every Relay Seat on the licence is in use. |
| Sign-in lockout | Administrators | A network address is locked out after too many failed sign-ins. |
| Administrator account or role change | Administrators | An administrator account is created or deactivated, someone is made or stops being an administrator, or an administrator role is created, changed or deleted. |
| Password set by an administrator | Administrators | One administrator sets another account's password. |
| Security settings changed | Administrators | The Security page, System Settings or the email delivery settings are saved. |
| Tenant seat limit reached | The tenant | A launch on a tenant's address is refused because the tenant's own seat allocation is used up. |
The messages are built in. You can reword, translate and switch off each one, but you cannot delete them or add new ones.
Connecting to your mail server
DartRelay sends mail through an SMTP server — your own mail server, Microsoft 365, Google Workspace or a mail relay service.
- Open the delivery settings. In the console, go to Email → Delivery.
- Enter your mail server's details: its address and port, whether to use an encrypted connection, the account name and password if the server requires them, and the address messages should come from.
- Save.
- Send a test. Open any template under Email → Templates and send a test to yourself (see Sending a test).
Use a mailbox or relay account dedicated to DartRelay, rather than a person's own account. Ask your mail administrator whether the server requires the "from" address to match the account you sign in with — many do.
When the delivery settings are saved, DartRelay sends the "security settings changed" message to administrators through the previous mail server settings, before the change is made. Someone cannot quietly point DartRelay's mail elsewhere without the existing administrators hearing about it.
Administrator notifications
The administrator messages go to the addresses in the Admin Notification Emails box.
- Open System Settings. Go to System → Settings.
- Enter the addresses in Admin Notification Emails. Separate them with commas, semicolons or new lines. A list pasted from Word, Outlook or a web page is fine.
- Save. Each address is checked. If one has a typing mistake, the save is refused and the faulty address is named, so nothing is dropped without your knowing. A summary under the box shows what will be stored.
- The list can hold up to 20 addresses.
- When the list itself changes, the "security settings changed" message goes to both the old and the new addresses. Removing everyone from the list cannot happen unnoticed.
- If the box is empty, the templates list shows a red warning above the administrator messages, because they have nowhere to go.
- Administrator messages are rate-limited. A burst of failed sign-ins produces a few lockout messages, not hundreds.
Notifications to a tenant
If you serve several customers from one installation, each tenant can be told when its people are turned away because its seat allocation is full.
- Open the tenant's address. Go to Appearance → Tenancy & Branding and open the address's Access page, where the tenant's seat allocation is set.
- Enter the tenant's notification addresses, separated as above.
- Tick "BCC to admin" if your administrators should get a copy too. It is off by default, so that an installation with many tenants does not fill your inbox.
- Save.
The addresses belong to the tenant, not to one address, so a tenant reached on two addresses has one list. The tenant's message names the tenant and the seat figures, and tells the reader what they can do. It deliberately leaves out the network address of the person who was refused.
See Tenancy & Branding and Licensing and Relay Seats.
Editing a template
- Open the templates list. Go to Email → Templates. Each row shows the message, its audience and whether it is switched on.
- Open a template. The editor shows a "Goes to" line explaining who receives it.
- Edit the subject and the body. The body has the same formatting toolbar as Agreements and Announcements: bold, italic, headings, lists, links and so on.
- Add shortcodes where you want details filled in, such as
{user}for the person's name. The editor lists the shortcodes available for that message. - Save. The page shows the text exactly as it will be sent. If you pasted something the editor does not allow, such as a script, it is removed, and you can see that it has gone.
A plain-text version of every message is produced automatically from the formatted body, for mail programs that do not show formatting. You do not maintain it separately.
Switching a message off
Each template has an on/off switch. Off means the message is not sent at all. The editor tells you what switching off costs for that message, for example:
- Switching off the Email one-time code stops anyone completing an email second step. To stop using email codes, change the two-factor settings on Authentication → Security instead.
- Switching off the Tenant seat limit message means a tenant's people are refused with nobody at the tenant told why.
- Switching off the Password reset confirmation does not stop resets working; the server log notes that no confirmation was sent.
Languages
If you have more than one portal language switched on, the editor offers a subject and body for each. Each person receives the message in their own language, falling back to the original text where no translation has been written. See Languages.
Sending a test
The template editor can send a test of the message to an address you choose. Every shortcode is filled with an obvious sample value, so you can check both the wording and that your mail server delivers. This is also the quickest way to check the delivery settings.
Shortcodes
Shortcodes are names in curly brackets that DartRelay replaces with real details when a message is sent. They are the same shortcodes used in theme text, such as {user} on the portal home page.
| Shortcode | Replaced with |
|---|---|
{user} | The person's display name. |
{username} | The person's username. |
{portal} | The portal's name. |
{host} | The portal address the message relates to. |
{when} | The date and time of the event. |
{ip} | The network address the event came from (not offered in the tenant message). |
{code} | The one-time code, in the Email one-time code message. |
{link} | The reset link, in the Password reset link message. That message needs it to be useful. |
{tenant} | The tenant's name, in the tenant message. |
{seats}, {maxseats} | Seats in use and the tenant's allocation, in the tenant message. |
A shortcode that DartRelay does not recognise — a typing mistake such as {usre} — is left in the message exactly as typed, so you can spot it in a test. A recognised shortcode with nothing to fill it with is left empty.
Example
An IT provider runs DartRelay for its own staff and two client firms. It points Email → Delivery at its Microsoft 365 relay, puts its two senior engineers in Admin Notification Emails, and rewords the New user welcome message to include its help desk number. For each client firm's address it enters the client's office manager as the notification address, with "BCC to admin" ticked for the firm whose seat allocation is tight.
If something goes wrong
No messages arrive at all
Send a test from a template. If it does not arrive, check the delivery settings with your mail administrator: the server address, port, encryption, account and "from" address. The server log records why a send failed. See Logs and audit.
Administrators get no alerts
Check the Admin Notification Emails box on System → Settings is filled in, and that the templates list shows no red warning. Check that the individual message is switched on.
A welcome email was not sent to a new user
It is only sent when the account has an email address and the New user welcome message is switched on. The users list shows whether the welcome email was sent.
A message shows {something} literally
The shortcode is misspelt or not available in that message. Compare it with the list in the template editor.
People do not receive one-time codes
See Two-factor authentication: if something goes wrong.
Related pages
Two-factor authentication
Email codes at sign-in.
Password policy and self-service reset
Reset links and confirmations.
Tenancy & Branding
Tenants, their addresses and seat allocations.
Languages
Translating what DartRelay says.