Email

Platform transactional emails triggered by NATS events (invites, OTPs, billing alerts).

Overview

Quick start

bun be:email:dev

Or bun backend:dev / bun dev. In development, when neither RELOOP_API_KEY nor SMTP_HOST is set, mail falls back to Mailpit SMTP (localhost:1025). That fallback is development-only: see How system email is delivered.

Environment

apps/backend/email/.env (from bun setup / bun env:setup).

EMAIL_PORT=8022
PORT=8022
BASE_URL="https://local.reloop.sh"
NATS_URL=nats://localhost:4222
RELOOP_API_KEY=
RELOOP_SENDER_DOMAIN=
ONBOARDING_TEST_DOMAIN=
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_SECURE=false
NODE_ENV=development

How system email is delivered

System email is anything Reloop sends to your own users: sign-in codes, invitations, billing alerts. It is separate from customer mail, which always goes through mail.

The service picks a transport at startup, in this order:

The chosen transport is logged once on boot, so reloop logs email tells you which one is live:

System email transport: SMTP smtp.acme.test:587 (authenticated)

Choosing a transport

Through Reloop. Best once you have a verified sending domain. Create an API key in the organization that owns it, then set RELOOP_API_KEY and RELOOP_SENDER_DOMAIN. Your platform mail then gets the same delivery pipeline, tracking and logs as customer mail.

Through your own SMTP server. Set SMTP_HOST, plus SMTP_USER and SMTP_PASSWORD if it requires auth. Useful on day one, before any domain is verified, and for shops that already relay everything through Postmark, SES or an internal server. Leave RELOOP_API_KEY empty.

SMTP_HOST=smtp.postmarkapp.com
SMTP_PORT=587
SMTP_USER=your-token
SMTP_PASSWORD=your-token

Signing in before email works

A fresh install has no sending domain, so it cannot email you a code to log in and verify one. Self-host breaks that loop at /dashboard/setup: the installer prints a one-time setup key, and the wizard creates the first administrator with a password, so no email is needed. See VPS install.

DEFAULT_OTP is a development helper and is left empty on new installations. Installations upgraded from an older installer keep the fixed code they were given; remove it and restart once a transport above works.

Branding system email

APP_NAME sets the name used across every system email: the sender name, the subject line and the message body. Any value other than Reloop is shown as Self-hosted Reloop × <APP_NAME>, so mail carries both your name and the fact that it runs on Reloop.

APP_NAME=Contoso Mail

Leave it unset, or set it to Reloop, and everything stays plain Reloop, so existing deployments are unaffected. The installer defaults it to Reloop and preserves your value across re-runs.

The sign-in alert previously sent as Security Alert, which was the only sender that did not carry the product name. It is now <APP_NAME> Security, matching the Billing and Support senders.

[!NOTE] The email logo is loaded from BASE_URL, not from Reloop, so replace that asset in your own deployment if you rebrand.

[!NOTE] The Reloop attribution cannot be configured away. The shared footer also keeps Reloop's help link, copyright line and postal address regardless of APP_NAME.

Commands

Architecture

Next