@serve.zone/dcrouter 32.6.3 → 32.7.0

package/ts/classes.dcrouter.ts

@@ -50,10 +50,10 @@ import { TestingOperationWorker } from './testing/classes.testing-operation-work
 import { TestingDnsCleanupManager } from './testing/classes.testing-dns-cleanup-manager.js';
 import { AcmeAccountDoc, AcmeIssuanceDoc, AcmeDnsChallengeDoc, TestingRegistrationDoc, TestingZoneDoc,
   TestingDomainGrantDoc, TestingRequestReceiptDoc, TestingDnsMutationDoc, TestingCertificateJobDoc } from './db/documents/index.js';
-import { AcceptedEmailSpool, CoreMailGatewayManager, CoreMailGatewayStore, createCoreMailGatewayRuntime, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, GatewayMailDomainStore, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, SmtpAccountManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
+import { AcceptedEmailSpool, composeEmailServerTls, CoreMailGatewayManager, CoreMailGatewayStore, createCoreMailGatewayRuntime, deriveEmailTlsSource, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, EmailTlsManager, GatewayMailDomainStore, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, SmtpAccountManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
 import { WebPushManager } from './webpush/index.js';
 import type { IRoute } from '../ts_interfaces/data/route-management.js';
-import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings, IEmailServerSettingsSeed, TEmailOutboundMode, TEmailServerSettingsUpdate } from '../ts_interfaces/data/email-settings.js';
+import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings, IEmailServerSettingsSeed, IEmailTlsCertificateStatus, TEmailOutboundMode, TEmailServerSettingsUpdate, TEmailTlsSource } from '../ts_interfaces/data/email-settings.js';
 import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPerformanceConfig, TRemoteIngressHubSettingsUpdate } from '../ts_interfaces/data/remoteingress.js';
 import type { ISecurityCompiledPolicy } from '../ts_interfaces/data/security-policy.js';
 
@@ -312,6 +312,8 @@ export class DcRouter {
   public smartAcme?: plugins.smartacme.SmartAcme;
   public dnsServer?: plugins.smartdns.dnsServerMod.DnsServer;
   public emailServer?: UnifiedEmailServer;
+  /** Owns the SMTP listener certificate: source resolution, renewal relevance, served status. */
+  public readonly emailTlsManager = new EmailTlsManager();
   public radiusServer?: RadiusServer;
   public opsServer!: OpsServer;
   private opsServerStopped = false;
@@ -1679,9 +1681,10 @@ export class DcRouter {
           source: event.source,
         });
         // Renewals arrive here too. The SMTP listener holds its PEM material as
-        // listener-level Rust configuration, so a renewed mail-hostname
-        // certificate must be pushed or STARTTLS keeps serving the stale one.
-        void this.reapplyEmailTlsMaterial(event.domain);
+        // listener-level Rust configuration, so a renewed mail certificate
+        // must be pushed or STARTTLS keeps serving the stale one. Queued with
+        // the email lifecycle so it never races a listener restart.
+        void this.queueEmailLifecycleTask(() => this.reapplyEmailTlsMaterial(event.domain));
       });
 
       // Note: smartproxy v27.5.0 emits only 'certificate-issued' and 'certificate-failed'.
@@ -2082,7 +2085,12 @@ export class DcRouter {
       storageManager: this.smartMtaBlobStorageManager,
     };
 
-    const emailTls = await this.resolveEmailTlsMaterial();
+    const emailTls = await this.emailTlsManager.resolve({
+      source: this.getEmailTlsSource(),
+      tls: baseEmailConfig.tls,
+      requiredHostnames: this.emailRouteBuilder.getMailCertificateHostnames(),
+    });
+    const emailServerTls = composeEmailServerTls(baseEmailConfig.tls, emailTls);
     const tlsTerminatedPorts = this.resolveEdgeTerminatedEmailPorts(portMapping);
     this.logEmailAuthTransportPosture(emailConfigHasAuth(baseEmailConfig), emailTls, mappedEmailPorts, tlsTerminatedPorts, mappedSecurePort);
 
@@ -2093,7 +2101,7 @@ export class DcRouter {
       dkimKeyProvisioning: 'caller-managed',
       persistRoutes: this.options.emailConfig.persistRoutes ?? false,
       queue: queueOptions,
-      ...(emailTls ? { tls: { ...baseEmailConfig.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem } } : {}),
+      tls: emailServerTls,
       outbound: {
         ...baseEmailConfig.outbound,
         connectionProxyProvider: (context) => this.mailEgressCoordinator.provideConnectionProxy(context),
@@ -2335,101 +2343,42 @@ export class DcRouter {
     this.mailDnsSync.requestSync('email server start');
   }
 
-  /**
-   * Resolve the PEM material for the SMTP listener.
-   *
-   * SmartMTA consumes `tls.certPem`/`tls.keyPem`; a path-shaped `tls` block is
-   * ignored, which leaves the Rust listener with no TLS material at all — no
-   * STARTTLS on the plain submission ports. Resolution order matches the
-   * RemoteIngress tunnel precedent: explicit paths, then the ACME cert store.
-   *
-   * Explicitly configured paths that cannot be read FAIL STARTUP. Silently
-   * continuing without TLS is what produced a cleartext submission port in
-   * production, so a broken explicit configuration must be impossible to miss.
-   */
-  private async resolveEmailTlsMaterial(): Promise<{ certPem: string; keyPem: string; source: string } | undefined> {
-    const tlsConfig = this.options.emailConfig?.tls as (IUnifiedEmailServerOptions['tls'] & {
-      certPath?: string;
-      keyPath?: string;
-    }) | undefined;
-
-    if (tlsConfig?.certPem && tlsConfig?.keyPem) {
-      return { certPem: tlsConfig.certPem, keyPem: tlsConfig.keyPem, source: 'inline PEM' };
-    }
-
-    if (tlsConfig?.certPath || tlsConfig?.keyPath) {
-      if (!tlsConfig.certPath || !tlsConfig.keyPath) {
-        throw new Error(
-          'emailConfig.tls requires both certPath and keyPath when either is configured',
-        );
-      }
-      let certPem: string;
-      let keyPem: string;
-      try {
-        certPem = await plugins.fs.promises.readFile(tlsConfig.certPath, 'utf8');
-        keyPem = await plugins.fs.promises.readFile(tlsConfig.keyPath, 'utf8');
-      } catch (error: unknown) {
-        throw new Error(
-          `Unable to read the configured SMTP TLS material (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath}): ${(error as Error).message}`,
-        );
-      }
-      if (!certPem.trim() || !keyPem.trim()) {
-        throw new Error(
-          `The configured SMTP TLS material is empty (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath})`,
-        );
-      }
-      logger.log('info', `SMTP TLS material loaded from configured paths (${tlsConfig.certPath})`);
-      return { certPem, keyPem, source: `configured paths (${tlsConfig.certPath})` };
-    }
-
-    const mailHostname = this.options.emailConfig?.hostname;
-    if (mailHostname) {
-      try {
-        const stored = await ProxyCertDoc.findByDomain(mailHostname);
-        if (stored?.publicKey && stored?.privateKey) {
-          logger.log('info', `SMTP TLS material loaded from the stored ACME certificate for ${mailHostname}`);
-          return { certPem: stored.publicKey, keyPem: stored.privateKey, source: `stored ACME certificate for ${mailHostname}` };
-        }
-      } catch (error: unknown) {
-        logger.log('warn', `Unable to read the stored certificate for the mail hostname ${mailHostname}: ${(error as Error).message}`);
-      }
-    }
+  /** Effective SMTP certificate source: the DB-backed setting, or the documented default. */
+  public getEmailTlsSource(): TEmailTlsSource {
+    return this.emailSettingsManager?.getTlsSource() ?? deriveEmailTlsSource(this.options.emailConfig?.tls);
+  }
 
-    return undefined;
+  /** The certificate the running SMTP listener serves, checked now; undefined while it is stopped. */
+  public getEmailTlsCertificateStatus(): IEmailTlsCertificateStatus | undefined {
+    if (!this.emailServer || !this.options.emailConfig) return undefined;
+    return this.emailTlsManager.getStatus(this.emailRouteBuilder.getMailCertificateHostnames());
   }
 
   /**
-   * Push renewed TLS material to the running SMTP listener.
+   * Push an issued or renewed certificate to the running SMTP listener.
    *
-   * Only reacts to the mail hostname, and only when explicit paths are NOT
-   * configured — an operator-managed file pair is not superseded by an ACME
-   * renewal for the same name. SmartMTA restarts just the Rust listener when
-   * the PEM material actually changes.
+   * Material is resolved from the source of truth on every call and is never
+   * written back into the email configuration, so every renewal applies, not
+   * just the first one per process. Configured material is never superseded
+   * by an ACME issuance. SmartMTA restarts just the Rust listener when the PEM
+   * material actually changes.
    */
   private async reapplyEmailTlsMaterial(domainArg: string): Promise<void> {
     const emailServer = this.emailServer;
-    const mailHostname = this.options.emailConfig?.hostname;
-    if (!emailServer || !mailHostname) return;
-    if (domainArg.toLowerCase() !== mailHostname.toLowerCase()) return;
-    const tlsConfig = this.options.emailConfig?.tls;
-    if (tlsConfig?.certPath || tlsConfig?.keyPath) return;
+    const emailConfig = this.options.emailConfig;
+    if (!emailServer || !emailConfig) return;
 
     try {
-      const emailTls = await this.resolveEmailTlsMaterial();
-      if (!emailTls) return;
-      emailServer.updateOptions({
-        tls: { ...this.options.emailConfig?.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem },
+      const emailTls = await this.emailTlsManager.applyIssuance(domainArg, emailServer, {
+        source: this.getEmailTlsSource(),
+        tls: emailConfig.tls,
+        requiredHostnames: this.emailRouteBuilder.getMailCertificateHostnames(),
       });
-      if (this.options.emailConfig) {
-        this.options.emailConfig.tls = {
-          ...this.options.emailConfig.tls,
-          certPem: emailTls.certPem,
-          keyPem: emailTls.keyPem,
-        };
+      if (emailTls) {
+        logger.log('info', `Applied the SMTP TLS certificate (${emailTls.origin}) after issuance for ${domainArg}`);
       }
-      logger.log('info', `Pushed renewed SMTP TLS material for ${mailHostname} to the email listener`);
     } catch (error: unknown) {
-      logger.log('error', `Unable to apply renewed SMTP TLS material for ${mailHostname}: ${(error as Error).message}`);
+      logger.log('error', `Unable to apply the SMTP TLS certificate after issuance for ${domainArg}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
 
@@ -2471,7 +2420,7 @@ export class DcRouter {
    */
   private logEmailAuthTransportPosture(
     authConfigured: boolean,
-    emailTls: { source: string } | undefined,
+    emailTls: { origin: string } | undefined,
     mappedPorts: number[],
     tlsTerminatedPorts: number[],
     mappedSecurePort: number | undefined,
@@ -2487,12 +2436,12 @@ export class DcRouter {
     }
     logger.log(
       'info',
-      `SMTP transport posture: TLS material=${emailTls ? emailTls.source : 'NONE'}, edge-terminated ports=[${tlsTerminatedPorts.join(', ') || 'none'}], implicit-TLS port=${mappedSecurePort ?? 'none'}, AUTH-capable ports=[${authCapable.join(', ') || 'none'}]`,
+      `SMTP transport posture: TLS material=${emailTls ? emailTls.origin : 'NONE'}, edge-terminated ports=[${tlsTerminatedPorts.join(', ') || 'none'}], implicit-TLS port=${mappedSecurePort ?? 'none'}, AUTH-capable ports=[${authCapable.join(', ') || 'none'}]`,
     );
     if (authConfigured && !emailTls && cleartext.length > 0) {
       logger.log(
         'error',
-        `SMTP AUTH is configured but ports [${cleartext.join(', ')}] have no TLS material and no upstream TLS terminator — AUTH is refused there because credentials must never cross a cleartext channel. Configure emailConfig.tls.certPath/keyPath, or provision an ACME certificate for ${this.options.emailConfig?.hostname || 'the mail hostname'}.`,
+        `SMTP AUTH is configured but ports [${cleartext.join(', ')}] have no TLS material and no upstream TLS terminator — AUTH is refused there because credentials must never cross a cleartext channel. Provision an ACME certificate for ${this.options.emailConfig?.hostname || 'the mail hostname'} (managedCertificate source), or configure emailConfig.tls material (configuredMaterial source).`,
       );
     }
   }
@@ -2535,6 +2484,12 @@ export class DcRouter {
         throw new Error('EmailSettingsManager is not initialized');
       }
 
+      if (settings.tlsSource === 'managedCertificate') {
+        const hostname = settings.hostname?.trim() || this.emailSettingsManager.getPublicSettings().hostname || undefined;
+        await this.emailTlsManager.assertManagedCertificateAvailable(
+          this.emailRouteBuilder.getMailCertificateHostnames(hostname),
+        );
+      }
       const updatedSettings = await this.emailSettingsManager.updateSettings(settings, updatedBy);
       this.emailDomainManager?.setBaseEmailDomains(this.options.emailConfig?.domains as IEmailDomainConfig[] | undefined);
       await this.emailDomainManager?.syncManagedDomainsToRuntime();
@@ -2559,7 +2514,8 @@ export class DcRouter {
         await this.stopUnifiedEmailComponents();
       }
 
-      return updatedSettings;
+      const tlsCertificate = this.getEmailTlsCertificateStatus();
+      return tlsCertificate ? { ...updatedSettings, tlsCertificate } : updatedSettings;
     });
   }
   
@@ -2572,6 +2528,7 @@ export class DcRouter {
       if (this.emailServer) {
         const emailServer = this.emailServer;
         this.emailServer = undefined;
+        this.emailTlsManager.clear();
         this.acceptedEmailSpool.beginStop();
         try {
           await emailServer.stop();

package/ts/db/documents/classes.email-server-settings.doc.ts

@@ -1,7 +1,7 @@
 import type { IUnifiedEmailServerOptions } from '@push.rocks/smartmta';
 import * as plugins from '../../plugins.js';
 import { DcRouterDb } from '../classes.dcrouter-db.js';
-import type { IEmailPortConfig, TEmailOutboundMode } from '../../../ts_interfaces/data/email-settings.js';
+import type { IEmailPortConfig, TEmailOutboundMode, TEmailTlsSource } from '../../../ts_interfaces/data/email-settings.js';
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
@@ -23,6 +23,10 @@ export class EmailServerSettingsDoc extends plugins.smartdata.SmartDataDbDoc<Ema
   @plugins.smartdata.svDb()
   public emailPortConfig?: IEmailPortConfig;
 
+  /** SMTP certificate source; absent on settings persisted before it existed (see TEmailTlsSource). */
+  @plugins.smartdata.svDb()
+  public tlsSource?: TEmailTlsSource;
+
   @plugins.smartdata.svDb()
   public updatedAt: number = 0;
 

package/ts/email/classes.email-route-builder.ts

@@ -214,28 +214,37 @@ export class EmailRouteBuilder {
     return new Set(sourceRoutes.map((route) => route.name).filter(Boolean) as string[]);
   }
 
-  private getSmtpsCertificateHostnames(): string[] {
-    const configuredHostname = this.dcRouterRef.options.emailConfig?.hostname;
-    if (typeof configuredHostname !== 'string' || !configuredHostname.trim()) {
-      throw new Error('SMTPS port 465 requires a non-empty configured email hostname');
+  /**
+   * Hostnames every mail certificate must cover, normalized: the mail
+   * hostname and every enabled mail-edge hostname. The SMTPS route requests
+   * its certificate for exactly these names, and the SMTP listener's
+   * certificate is checked against them. `hostnameArg` evaluates a hostname
+   * that is not applied yet.
+   */
+  public getMailCertificateHostnames(
+    hostnameArg: string | undefined = this.dcRouterRef.options.emailConfig?.hostname,
+  ): string[] {
+    if (typeof hostnameArg !== 'string' || !hostnameArg.trim()) {
+      throw new Error('Mail certificates require a non-empty configured email hostname');
     }
-
     const candidates = [
-      configuredHostname,
+      hostnameArg,
       ...(this.dcRouterRef.remoteIngressManager?.getMailEdges() || [])
         .filter((edge) => edge.enabled && edge.tags?.includes(REMOTE_INGRESS_MAIL_TAG))
         .map((edge) => edge.mailHostname)
         .filter((hostname): hostname is string => typeof hostname === 'string' && Boolean(hostname.trim())),
     ];
-    const hostnames = new Set<string>();
-    for (const candidate of candidates) {
-      const normalized = candidate.trim().toLowerCase().replace(/\.$/, '');
-      if (normalizeOwnershipHostname(normalized) !== normalized) {
-        throw new Error(`SMTPS certificate hostname '${candidate}' is not a valid fully qualified domain name`);
+    return [...new Set(candidates.map((candidate) => candidate.trim().toLowerCase().replace(/\.$/, '')))].sort();
+  }
+
+  private getSmtpsCertificateHostnames(): string[] {
+    const hostnames = this.getMailCertificateHostnames();
+    for (const hostname of hostnames) {
+      if (normalizeOwnershipHostname(hostname) !== hostname) {
+        throw new Error(`SMTPS certificate hostname '${hostname}' is not a valid fully qualified domain name`);
       }
-      hostnames.add(normalized);
     }
-    return [...hostnames].sort();
+    return hostnames;
   }
 
   private shouldHydrateGeneratedEmailRoute(storedRoute: IRoute): boolean {

package/ts/email/classes.email-settings.manager.ts

@@ -3,12 +3,18 @@ import { EmailServerSettingsDoc } from '../db/index.js';
 import { logger } from '../logger.js';
 import { isSmtpAccountRouteName } from './classes.smtp-account.manager.js';
 import { isWorkAppManagedMailRouteName } from './classes.workapp-mail-manager.js';
+import {
+  deriveEmailTlsSource,
+  hasConfiguredEmailTlsMaterial,
+  withoutConfiguredEmailTlsMaterial,
+} from './classes.email-tls-manager.js';
 import type { IDcRouterOptions } from '../classes.dcrouter.js';
 import type {
   IEmailPortConfig,
   IEmailServerSettings,
   TEmailOutboundMode,
   TEmailServerSettingsUpdate,
+  TEmailTlsSource,
 } from '../../ts_interfaces/data/email-settings.js';
 
 const defaultEmailPorts = [25, 587, 465];
@@ -26,6 +32,7 @@ export class EmailSettingsManager {
   private cachedEmailConfig?: IUnifiedEmailServerOptions;
   private cachedEmailPortConfig?: IEmailPortConfig;
   private outboundMode: TEmailOutboundMode = 'remoteIngress';
+  private tlsSource: TEmailTlsSource = 'managedCertificate';
   private enabled = false;
   private updatedAt = 0;
   private updatedBy = 'default';
@@ -99,6 +106,11 @@ export class EmailSettingsManager {
     return this.outboundMode;
   }
 
+  /** Effective SMTP certificate source, including the default for settings persisted without one. */
+  public getTlsSource(): TEmailTlsSource {
+    return this.tlsSource;
+  }
+
   public getPublicSettings(): IEmailServerSettings {
     const emailConfig = this.cachedEmailConfig;
     const emailPortConfig = this.cachedEmailPortConfig;
@@ -110,6 +122,7 @@ export class EmailSettingsManager {
       portMapping: emailPortConfig?.portMapping ? { ...emailPortConfig.portMapping } : null,
       receivedEmailsPath: emailPortConfig?.receivedEmailsPath || null,
       maxMessageSize: emailConfig?.maxMessageSize ?? null,
+      tlsSource: this.tlsSource,
       domainCount: emailConfig?.domains?.length || 0,
       routeCount: emailConfig?.routes?.length || 0,
       authUserCount: emailConfig?.auth?.users?.length || 0,
@@ -129,7 +142,15 @@ export class EmailSettingsManager {
     }
 
     const nextEnabled = hasOwn(updates, 'enabled') ? Boolean(updates.enabled) : doc.enabled;
+    const nextTlsSource = updates.tlsSource === undefined
+      ? doc.tlsSource
+      : this.normalizeTlsSource(updates.tlsSource);
     const nextEmailConfig = this.patchEmailConfig(doc.emailConfig ?? undefined, updates, nextEnabled);
+    if (updates.tlsSource === 'configuredMaterial' && !hasConfiguredEmailTlsMaterial(nextEmailConfig?.tls)) {
+      throw new Error(
+        'The configuredMaterial email TLS source requires emailConfig.tls certificate material (certPem/keyPem or certPath/keyPath); none is persisted',
+      );
+    }
     const nextEmailPortConfig = this.patchEmailPortConfig(doc.emailPortConfig ?? undefined, updates);
     const nextOutboundMode = this.patchOutboundMode(doc.outboundMode, updates);
 
@@ -137,6 +158,7 @@ export class EmailSettingsManager {
     doc.emailConfig = nextEmailConfig;
     doc.emailPortConfig = nextEmailPortConfig;
     doc.outboundMode = nextOutboundMode;
+    doc.tlsSource = nextTlsSource;
     doc.updatedAt = Date.now();
     doc.updatedBy = updatedBy;
     if (doc.creationStatus === 'new') {
@@ -150,6 +172,7 @@ export class EmailSettingsManager {
           updatedBy: doc.updatedBy,
           ...(doc.emailConfig !== undefined ? { emailConfig: doc.emailConfig } : {}),
           ...(doc.emailPortConfig !== undefined ? { emailPortConfig: doc.emailPortConfig } : {}),
+          ...(doc.tlsSource !== undefined ? { tlsSource: doc.tlsSource } : {}),
         },
         $unset: {
           ...((hasOwn(updates, 'portMapping') || hasOwn(updates, 'receivedEmailsPath'))
@@ -169,6 +192,7 @@ export class EmailSettingsManager {
     this.cachedEmailConfig = clonePlain(doc.emailConfig ?? undefined);
     this.cachedEmailPortConfig = clonePlain(doc.emailPortConfig ?? undefined);
     this.outboundMode = this.normalizeOutboundMode(doc.outboundMode);
+    this.tlsSource = doc.tlsSource ?? deriveEmailTlsSource(doc.emailConfig?.tls);
     this.updatedAt = doc.updatedAt;
     this.updatedBy = doc.updatedBy;
   }
@@ -197,6 +221,13 @@ export class EmailSettingsManager {
     return mode;
   }
 
+  private normalizeTlsSource(sourceArg: TEmailTlsSource): TEmailTlsSource {
+    if (sourceArg !== 'managedCertificate' && sourceArg !== 'configuredMaterial') {
+      throw new Error(`Invalid email TLS source: ${String(sourceArg)}`);
+    }
+    return sourceArg;
+  }
+
   private patchEmailConfig(
     existingConfig: IUnifiedEmailServerOptions | undefined,
     updates: TEmailServerSettingsUpdate,
@@ -240,6 +271,17 @@ export class EmailSettingsManager {
       nextConfig.routes = this.removeRoutesByName(nextConfig.routes || [], updates.removeRouteNames);
     }
 
+    // The managed certificate supersedes operator-managed material, so the
+    // material is removed rather than left behind as a dormant override.
+    if (updates.tlsSource === 'managedCertificate') {
+      const remainingTls = withoutConfiguredEmailTlsMaterial(nextConfig.tls);
+      if (remainingTls) {
+        nextConfig.tls = remainingTls;
+      } else {
+        delete nextConfig.tls;
+      }
+    }
+
     if (nextEnabled) {
       if (!nextConfig.hostname?.trim()) {
         throw new Error('Email hostname is required when email is enabled');