Account email

Flare can send verification, password recovery, and email-change messages through your SMTP provider. Sending, password recovery, and required verification are separate choices. You can enable recovery for your users without making verification a condition of using the instance.

Open Settings → Email with settings.email (and settings.read to navigate Settings). Account-specific verification/exemption actions instead use users.email and obey account hierarchy. A role with Administrator includes both capabilities. No additional queue service or worker container is required; messages are queued in PostgreSQL and sent by the running Flare application.

Test your provider before enabling automatic account mail.

Test your provider before enabling automatic account mail.

Set up delivery

1. Enter the SMTP hostname and port supplied by your provider.
2. Select TLS for implicit TLS, usually port 465, or STARTTLS for a connection that must upgrade to TLS, usually port 587. Flare defaults to TLS on 465.
3. Enable authentication and enter the provider's username and password. An explicitly trusted local relay can use no authentication and/or no encryption when appropriate to that relay.
4. Set a sender address the provider authorizes, a display name, and optional Reply-To.
5. Set the public Flare URL, or let it use NEXTAUTH_URL. It must use HTTPS outside localhost testing. Keep it on the same origin as NEXTAUTH_URL: it only builds the links in messages, and someone who signs in at another origin can't change their account email there. Earlier builds accepted email changes from the public URL's origin too.
6. Choose Test connection, then Send test email to an address you control. Open the inbox to confirm receipt.
7. Turn on Enable email and choose Save email settings when you are satisfied with the result.

The bar with Save email settings sits at the end of the settings and shows whether you have unsaved changes. Its buttons become available once you change something; Discard returns every field to the saved settings. Email settings save separately from the rest of Settings. Delivery status, below the bar, is not part of that save; its Refresh delivery status and Retry delivery buttons act immediately.

Tests can use the draft configuration before saving or enabling automatic email. Connection testing checks connectivity/authentication; sending tests SMTP acceptance of sender and recipient. Send test email without a recipient says A test recipient is required; earlier versions reported it as an SMTP failure. Test messages count toward the daily cap. Server acceptance does not guarantee inbox delivery.

A value the form can't accept, or a draft that can't be enabled as it is, such as one without an SMTP host, is refused with a message that says what to change. If saving or testing fails for any other reason, Flare shows Could not update email settings and the server logs the cause. That includes saved email settings the server can't read, a FLARE_EMAIL_* override that isn't valid, and an encryption key that is missing, too short or different from the one that encrypted the saved credentials: only the operator can fix those, in the deployment's environment. Earlier versions answered those failures with the failure's own text, which could describe internals rather than the settings.

Certificate verification stays enabled. For a private relay with a custom certificate authority, supply the CA in advanced SMTP settings or through FLARE_EMAIL_SMTP_CA_FILE.

Saved SMTP passwords are write-only in the settings view. Leaving the password input empty preserves the existing password; the explicit clear action removes it. Keep the active encryption key stable across deployments.

Saved email settings, including the access policy, apply from the next request without a restart, on every replica. Values set through the environment change only when the app is recreated; see environment-managed configuration.

Choose an access policy

Verification mode	New accounts	Existing accounts
Off	No verification gate	Keep access; recovery enrollment can still be available
Optional	Receive verification mail but can use Flare before verifying	Keep access
Required for new users	Accounts created after activation must verify for protected features	Earlier accounts keep access
Required for all users	New accounts must verify immediately	Unverified existing accounts get the configured grace period

The default is Off. The default existing-user grace period is 7 days, configurable from 0–90 days. Activating all-user enforcement requires reviewing the affected-user count in the dashboard: it counts the accounts that are neither verified nor exempt, which lose access to protected features when the grace period ends. At least one administrator must already have trusted verification proof or an explicit exemption before that policy can be saved; otherwise saving is refused with a 409 and the previous policy stays in force.

Turning enforcement off and back on establishes a new activation boundary. Moving into all-user mode starts a new existing-user grace window. Do not treat a policy toggle as a permanent record of which historical users were once required to verify.

When verification is required, a user can sign in to the restricted account flow and complete verification, but normal protected features and authenticated uploads remain gated until they do. Exempt users retain access without proving an address. You can choose whether administrator-created users inherit the policy or are exempt.

Recovery and verification can be rolled out independently.

Recovery and verification can be rolled out independently.

A staged rollout for an existing instance

1. Configure and test SMTP with recovery/verification enforcement still off.
2. Enable sending and password recovery.
3. Enroll and verify your administrator recovery address from Profile.
4. Ask existing users to enroll their own addresses while they still have access.
5. Enable optional or new-user verification if desired.
6. Only move to all-user enforcement after reviewing its impact and allowing a realistic grace period.

An upgrade leaves email disabled and keeps existing access unchanged. Older emailVerified timestamps may have been created without an actual mailbox confirmation, so Flare does not accept them as proof. No upgrade automatically sends enrollment mail to old accounts.

Password recovery

Recovery works for local-password accounts whose current email address has verified proof. It is disabled by default. Once enabled, an eligible user can request a reset from the sign-in flow, open the link, and submit a new password.

Reset links expire after 30 minutes by default, configurable from 5–120 minutes. Opening the link does not consume it; submitting the reset does. The new password follows the rules for every account password, at least 8 characters and at most 72 UTF-8 bytes, and Flare stores only its bcrypt hash. Successful reset invalidates browser sessions and obsolete email action/reset tokens, while preserving both authenticator and dedicated passkey recovery codes. The legacy upload token is preserved unless Rotate upload tokens after a password reset is enabled; scoped API tokens should be managed separately.

Recovery requests do not reveal whether the submitted email belongs to an eligible account. If an old user never enrolled a recovery address, an administrator must help them regain access; the stored address alone is insufficient. An exemption from verification does not enable recovery.

A password reset does not disable two-factor authentication, reset either recovery-code set, remove passkeys, or turn off Require passkey to sign in. With that requirement off, a user with local two-factor authentication still needs their authenticator or an unused authenticator recovery code after resetting the password. With it on, the new password cannot sign in: use a registered passkey or a dedicated passkey recovery code. Email verification remains enforced after passkey or emergency recovery sign-in when required by policy.

SSO-only accounts using provider sign-in recover through that provider. An SSO-only account that explicitly requires passkeys instead uses its registered passkeys or dedicated passkey recovery codes; the code plus current account email grants emergency access without the provider. OIDC auto-login's enforceSso setting disables local email password recovery, while preserving the local login page for permitted sign-in methods. Keep an administrator method that remains usable under the account's own requirement.

Email changes

With email enabled, confirmed changes are available by default. Users recently authenticate, request a new address, and confirm it before it replaces the current one. You can additionally require approval at the old address.

The old address stays active until the required confirmations finish. Cancelling a change invalidates its pending links. Verification links default to 24 hours, configurable from 1–168 hours. Link scanners opening a message do not finish the confirmation; a user must explicitly confirm.

A legacy unverified address does not need to receive approval mail unless the two-address policy explicitly requires it. If you enable old-address approval while a change is already pending, that user may need to restart their change so both links can be issued.

When an account requires passkeys, starting enrollment or a confirmed email change requires a passkey or dedicated passkey-recovery sign-in within five minutes, including for SSO-only accounts. Password or provider proof does not replace it. Changing the address preserves the requirement and dedicated codes; future emergency sign-in uses the new address. Other address-verification and mailbox-approval rules remain in force.

SSO email trust

Two separate controls affect SSO:

• Settings → Access → Require verified email controls whether a new OIDC identity needs the provider's email_verified=true claim before Flare creates its account.
• Settings → Email → Trust verified SSO email controls whether that provider proof also satisfies Flare's account-email policy.

The second control is off by default. When enabled, proof is tied to the account's current email and configured identity. Disabling trust stops accepting proof based solely on an OIDC claim. Neither option links accounts with matching email addresses. Full SSO guide.

Brand account messages

Advanced branding includes instance name, logo URL, accent color, support address, footer, introductory text, subject prefix, and separate verification/reset/change subjects. Flare generates HTML and plain-text versions and escapes the configured text. It does not accept arbitrary HTML email templates, attachments, or executable template code.

Use sender-domain SPF, DKIM, and DMARC settings as provided by your mail service. Flare does not receive provider bounce webhooks in this release, so investigate provider logs when mail is accepted but does not arrive.

Limits and delivery history

Defaults are a 60-second resend interval, 5 messages per address per hour, 20 per IP per hour, and a daily admission cap of 500. Rate-limit accounting is stored in PostgreSQL. Your reverse proxy must supply trusted client-IP headers for IP limits to work as intended; the per-IP limit uses the same client address as sign-in and request limits, described in client addresses and rate limits. A request over the resend interval or an hourly limit gets 429 with Retry-After set to the seconds until that limit's window ends. Once the daily cap is used up, registration, account email requests and accounts created by administrators that would send mail are refused with 400 and The daily email sending limit has been reached. Try again tomorrow or contact your administrator.; earlier versions answered Unable to complete this email request. Please try again. Each window opens with the first request it counts, and refused requests don't extend it. Earlier versions always sent Retry-After: 60, so a client that waited that long could be refused again until the hour ended.

Queued messages survive restarts. Every running Flare process checks the queue every 5 seconds, starting when the process starts, and uses the settings in effect at each check: sending resumes on the first check after a restart, and saving these settings or choosing Retry delivery takes effect on the next check without a restart. A message that was being sent when its process stopped is tried again once its lease expires, 2 minutes after that attempt began or five SMTP timeouts if that is longer, or is marked failed if it has no attempts left. Workers use leases to coordinate attempts and default to 2 concurrent sends, 3 attempts, and 60-second initial retry delay with exponential backoff. An expired or revoked account link cannot be made useful by retrying its old message.

Settings → Email shows pending, processing, accepted/sent, and failed deliveries with masked recipients and sanitized error messages. Retry an eligible failed message after fixing its cause. Retrying uses the same token rather than creating a new account action. Successful/expired message bodies are cleared, and diagnostic history follows the default 14-day retention setting.

SMTP delivery is at-least-once: a crash after acceptance can cause the same message to be sent again. Account tokens are still single-use. Disabling email through the settings save cancels pending/processing mail. SMTP failure does not automatically relax verification policy or make container liveness fail.

Environment-managed configuration

For deployment-managed SMTP, add settings to the app's environment. This example uses a mounted password file:

FLARE_EMAIL_ENABLED=true
FLARE_EMAIL_SMTP_HOST=smtp.example.com
FLARE_EMAIL_SMTP_PORT=587
FLARE_EMAIL_SMTP_SECURITY=starttls
FLARE_EMAIL_SMTP_AUTHENTICATION=true
FLARE_EMAIL_SMTP_USERNAME=flare
FLARE_EMAIL_SMTP_PASSWORD_FILE=/run/secrets/flare_smtp_password
FLARE_EMAIL_FROM_ADDRESS=flare@example.com
FLARE_EMAIL_PUBLIC_URL=https://files.example.com
FLARE_EMAIL_RECOVERY_ENABLED=true
FLARE_EMAIL_VERIFICATION_MODE=new_users

Mount the referenced file so the app user can read it, and add these variables to the Flare service's environment; putting new keys in Compose's .env alone does not automatically pass them into the container. Redeploy after changes.

Every operator-facing email setting has an override and optional _FILE form, named FLARE_EMAIL_ plus the setting's key in upper snake case: Accounts created by administrators (verification.adminCreated) is FLARE_EMAIL_VERIFICATION_ADMIN_CREATED. Overrides take precedence and never overwrite the saved fallback. Settings → Email shows Managed by environment under each overridden control and keeps it read-only. See the complete variable/default reference.

Recover from an email lockout

At the deployment layer, set:

FLARE_EMAIL_ENABLED=false

Recreate/redeploy the app with that value passed into its environment. It disables sending and local email verification enforcement, even if an old encryption key is lost. To keep sending while relaxing the access gate, use FLARE_EMAIL_VERIFICATION_MODE=off instead.

Open /auth/login?local=1 and use an allowed administrator method: the local password and required authenticator, or a passkey. If that account requires passkeys, use a passkey or dedicated passkey recovery code instead of the password. Repair the configuration, verify recovery access, then remove the override and redeploy. This does not reset passwords, bypass authentication, disable SSO configuration, or turn off a passkey requirement.

If decryption is the problem, restore the original key from your secret backup. Changing to a new key requires re-entering credentials and replacing affected queued messages. It also makes webhook signing secrets unreadable, and creators can no longer copy existing invite links again, although those links keep working. Key rotation and backups.