The platform sends password-reset, email-verification, and invitation emails. Platform administrators configure the mail server. Each email contains a link to the dashboard:
| Sent when | Link | |
|---|---|---|
| Password reset | Someone requests a reset at POST /v1/auth/password/forgot, or an admin resets a password | /reset-password?token=…, valid for 30 minutes |
| Email verification | A password account registers or requests another message at POST /v1/auth/email/verify/resend | /verify-email?token=…, valid for 2 days |
| Invitation | An admin creates an invitation addressed to an email | /invite/{token}, valid until the invitation expires |
Email links use server.dashboard_base_url, falling back to server.public_base_url. The platform does not send these emails if neither setting is configured; it logs a warning. The link does not use the request’s Host header.
Configuring a mail server
Section titled “Configuring a mail server”Set mail infrastructure in the platform config file or environment. The mail password is a secret, like storage credentials.
mail: backend: smtp # log (default) | smtp smtp: host: smtp.example.com port: 587 username: apikey starttls: true # password: prefer the SMTP_PASSWORD env var| Key | Default | Description |
|---|---|---|
backend | log | log writes each message to the server log. You can copy links from the log. smtp sends messages through SMTP. |
from_address | no-reply@localhost | The sender’s From header. |
smtp.host / smtp.port | localhost / 587 | SMTP relay host and port. |
smtp.username / smtp.password | unset | The platform logs in when smtp.username is set. SMTP_PASSWORD overrides the configured password. |
smtp.starttls | true | Starts TLS after connecting. Implicit TLS on port 465 is not supported; use a STARTTLS port such as 587. |
Requiring a verified email
Section titled “Requiring a verified email”When registration.require_verified_email is enabled, the platform refuses human sessions for accounts with unconfirmed email addresses on org-scoped endpoints. This admin-editable setting defaults to false. A blocked request returns 403 and identifies POST /v1/auth/email/verify/resend as the verification endpoint. GET /v1/auth/me reports email_verified and email_verification_required.
The platform marks accounts created through SSO, social login, or SCIM as verified at creation. It also marks the bootstrap admin as verified. A password-reset link also verifies the email address.
Enable this setting only after configuring mail.backend: smtp. With the log backend, the platform does not deliver verification links.
Changing what an email says
Section titled “Changing what an email says”Each email template has a subject and a plain-text body. Both use Python str.format fields. A product mounted on the platform can register a new template or replace a platform template by name:
from opentremor_platform.controllers.services.mail.templates import register_mail_template
register_mail_template( "password_reset", subject="Reset your {product_name} password", body="Choose a new password: {link}\nThe link expires in {expires_in}.\n",)Every template receives product_name from branding.product_name. The platform provides these templates:
| Template | Fields |
|---|---|
password_reset | link, expires_in |
email_verification | link, expires_in |
invitation | link, org_name, role, expires_at |
backup_key_change | actor, action, recipient, label, effective_at |