Realm mail and mail templates

The realm sends mail of its own: sign-in and reset codes, invitations, notices, invoices. This page is about that mail: where it leaves from, how to send it through the realm’s own mail server, and the templates every one of those mails is made from. Mail hosting for your customers (domains, mailboxes, webmail) is in Mail.

Where the realm’s mail leaves

The realm tries these in order and uses the first that is ready:

1. A mail channel in Manager › Notifications: an enabled provider that the mail route goes to, such as the shipped E-mail (SMTP) provider.
2. The mail server from the setup wizard, if one was entered there.

A mail the channel refuses is never sent another way and never dropped silently. The person who asked for it is told it failed (a sign-in code that could not be sent says so), and every operator gets one notice per channel and time window, opening Notifications.

Send through the realm’s own mail server

When the realm runs mail for its customers, its own mail can go through the same server. Mail then leaves from an ordinary mailbox of the realm’s domain, signed and checked with that domain’s DKIM, SPF and DMARC like any other.

Before you start, the realm’s mail server must be reachable on its mail ports: in Networks › Load balancers, a balancer on the mail server app with its ports (25, 465, 587, 993 and the rest), the mail app’s network allowed out, and no network policy blocking outbound SMTP for the operators’ organisation. Port 25 must be open outbound at your provider, and the reverse DNS of the balancer’s address must name the mail server.

1. The domain. In Mail › Domains, as the operators’ organisation, add the realm’s domain (for example cloud.example.se). It must be verified for that organisation. If the realm’s nameserver serves the domain, its MX, SPF, DKIM and DMARC records are published for you; otherwise the domain’s page lists them to set.
2. The mailbox. In Mail › Mailboxes, add no-reply@<the realm's domain>. On its row, make an app password with the label notices. Copy it: it is shown once.
3. The channel. In Manager › Notifications, add the E-mail (SMTP) provider and fill in:

   Field	Value
   Mail server	mail.<the realm's domain>
   Port	587
   Encryption	starttls
   User name	no-reply@<the realm's domain>
   Password	the app password
   Sender address	no-reply@<the realm's domain>
   Sender name	your company’s name, for example

   
   Enable it and turn its mail route on.
4. Test. Send a test through it. Then sign out and ask for a sign-in code to an address outside the realm, and check that it arrived with SPF and DKIM passing.
5. The fallback. In the setup wizard’s mail step, enter the same server and user with a second app password, or clear it. Don’t leave an old relay there: it is used whenever the channel isn’t ready.

The app password is kept sealed in the provider’s settings and never shown again. To rotate it, make a new one on the mailbox, paste it into the provider, then revoke the old one. Revoking it touches nothing else on the mailbox.

Mail templates

Every mail the platform sends is a template: a sign-in code, a password reset, an organisation invite, a platform invite, a notice by mail, the daily digest, an invoice. Each module ships its own, in English and Swedish, and you edit them all in one place: Manager › Email templates.

• The list shows each template’s title, its key (such as onboarding.reset or billing.invoice) and where its text comes from: the shipped default, the realm’s, or a reseller’s.
• Open one to edit it per language: the subject, the text, and optionally an HTML version. The variables it may use are listed beside it, with what each holds, and a preview shows it filled with samples.
• Save keeps your text. Reset to default removes it, and the shipped text applies again. Send a test to me mails it to your own address.

The template language

A variable is its name in braces: {link}, {code}, {org}. A plural picks a form by a number:

{days, plural, =0 {today} one {in # day} other {in # days}}

There is nothing else: no logic, no includes, nothing run as code. A brace that isn’t one of those two forms is plain text, so CSS in the HTML keeps working. In the HTML version every value is escaped. Saving refuses a template that uses a variable the template doesn’t have.

Layout and resellers

• notices.layout is the frame every HTML mail is put in. It must keep {content}, and may use {signature} (the sender’s name and support lines). A template with no HTML version goes out as plain text.
• A reseller edits templates for its own customers on its organisation’s page, in the same editor. Its customers get its text; everyone else keeps the realm’s. A reseller never sees another reseller’s templates.
• Language: a mail goes out in the person’s language, else the realm’s, else English. For each, a reseller’s text comes first, then the realm’s, then the default.

When a template breaks

If a module update drops a variable your text uses, that text can no longer be filled in. The mail then goes out with the next text in line (the realm’s, or the default), the template is marked broken in the editor, and whoever saved it gets a notice. Nobody misses a mail because of it. Save or reset the template to clear the mark.

Next

• Mail
• Sign-up and invites