Email notifications

Open Gauge can send email for four things: confirming new accounts, resetting a forgotten password, keeping a calibration's owning organization aware of its status, and alerting organization admins to a join request. Like Gogs/Gitea, SMTP is a single, admin-managed configuration rather than something every user touches.

Every one of these events (except account verification and password reset, which have no in-app equivalent) also raises an in-app notification — the bell icon in the top bar — regardless of whether SMTP is configured; email is a bonus on top of that, not the only way to find out. See Notifications for the full list of categories, the inbox itself, and how each user chooses which channels they want per category from Settings → Notifications. See also Organizations → Join requests.

Configuration

SMTP settings live in the database, not environment variables — they're edited from Admin → Email by any admin or superadmin user, and take effect immediately (no restart required). This keeps mail configurable at runtime in a self-hosted deployment without rebuilding or redeploying the container.

For the step-by-step walkthrough (which fields to fill in, provider-specific settings for Gmail / Office 365 / SendGrid / Mailgun, and troubleshooting), see Configuring email (SMTP). The short version: host, port, optional username/password, a from address/name, an enabled toggle, and a reminder lead time in days — plus a Send test email action to validate the configuration before turning it on. See Admin in the API Reference for the underlying /admin/email-settings endpoints.

Behavior when mail isn't configured

Open Gauge must keep working out of the box in Docker Compose (see Self-hosting: Deployment) even though no self-hosted install has SMTP configured by default. So every email-sending code path checks whether mail is enabled first, and degrades to a manual, admin-mediated fallback instead of failing outright:

• Registration still creates the account, but it starts unverified — since there's no way to email a verification link, an admin/superadmin must activate it manually from Admin → Users (a "Pending activation" badge and Activate button appear there).
• Forgot password has no self-service path at all without SMTP — the sign-in screen tells the user to contact their administrator, who can be asked to help them regain access.
• Calibration notifications and reminders still raise their in-app notification as normal — only the email half is skipped. See Notifications.

Nothing about account creation or calibration workflows is blocked by mail being unconfigured — only the automated, self-service parts of it are.

Account verification

Every self-registered account (POST /auth/register) starts unverified and cannot sign in until activated — there is no path where self-registration grants instant access, regardless of mail configuration.

Exception: the very first account on a fresh install. With zero users in the database there is no admin who could activate anyone, so that first registration is created verified, with role superadmin, and can sign in immediately. Every account registered after that follows the normal activation flow below.

What activation looks like for everyone after the first account depends on whether mail is enabled:

With mail enabled:

1. The account is created with is_verified = false and a random verification token (24-hour expiry).
2. A verification email is sent with a link to /auth/verify-email?token=....
3. POST /auth/login rejects unverified accounts until the link is clicked.
4. Clicking the link calls GET /auth/verify-email, which marks the account verified and returns an access token — the user lands signed in.

If the email never arrives (e.g. the admin hasn't finished the SMTP setup), the user can request another one from the sign-in screen (POST /auth/resend-verification), which always responds successfully without revealing whether the address exists.

Without mail enabled: the account is created unverified with no token issued (there's nowhere to send it). An admin/superadmin activates it directly from Admin → Users — this sets is_verified = true with no email round-trip.

Accounts created directly by an admin (POST /users) are unaffected by any of this — they're verified immediately, since an admin already vouched for them when creating the account.

Forgot password

POST /auth/forgot-password always responds successfully regardless of whether the address exists, to avoid leaking account existence — the frontend shows one generic message either way.

With mail enabled: if the address matches an account, a reset token (1-hour expiry) is generated and emailed with a link to /auth/reset-password?token=.... Submitting a new password there (POST /auth/reset-password) clears the token, updates the password, and signs the user in.

Without mail enabled: no token is ever generated — there is no self-service reset path. The sign-in screen's messaging says so explicitly, directing the user to their administrator, who can reset the password by re-creating credentials or otherwise assisting them out-of-band.

Calibration notifications

Two events notify every active Technician, Admin, and Super Admin in an asset's organization, via an in-app notification and (if configured) email — each recipient's own preferences from Settings → Notifications decide which channels they actually get (see Notifications). See Data model & concepts for how assets and organizations relate; Viewers are never notified since they can't act on a calibration:

• New calibration recorded — as soon as POST /calibrations succeeds, the organization's technicians and admins are notified (except the person who just logged it).
• Due soon / overdue — a daily sweep (07:00 server time) checks every active asset's latest calibration. Each calibration is reminded at most once per threshold: once when it enters the configured reminder window, and once more if it lapses into overdue. A calibration is only marked as reminded once at least one channel actually delivers for at least one recipient (in-app notification created, or email sent); if none does — e.g. mail isn't configured and every recipient has opted out of in-app for that category — it's retried on the next day's sweep instead.

All of this is best-effort: a failed send is logged and never blocks the calibration being recorded, and the daily sweep as a whole never raises past its own log entry.