@serve.zone/dcrouter 14.1.0 → 14.2.1

package/ts/classes.dcrouter.ts

@@ -5,17 +5,21 @@ import * as paths from './paths.js';
 
 // Import the email server and its configuration from smartmta
 import {
+  type Email,
   UnifiedEmailServer,
   type IUnifiedEmailServerOptions,
   type IEmailRoute,
   type IEmailDomainConfig,
   type IStorageManagerLike,
+  type IExtendedSmtpSession,
+  type IMessageAcceptanceContext,
+  type IMessageAcceptanceDecision,
 } from '@push.rocks/smartmta';
 import { logger } from './logger.js';
 import { StorageBackedCertManager } from './classes.storage-cert-manager.js';
 import { CertProvisionScheduler } from './classes.cert-provision-scheduler.js';
 // Import unified database
-import { DcRouterDb, type IDcRouterDbConfig, CacheCleaner, ProxyCertDoc, AcmeCertDoc } from './db/index.js';
+import { DcRouterDb, type IDcRouterDbConfig, CacheCleaner, ProxyCertDoc, AcmeCertDoc, CachedEmail } from './db/index.js';
 // Import migration runner and app version
 import { createMigrationRunner } from '../ts_migrations/index.js';
 import { commitinfo } from './00_commitinfo_data.js';
@@ -38,6 +42,45 @@ import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPer
 import type { ISecurityCompiledPolicy } from '../ts_interfaces/data/security-policy.js';
 
 type TInboundProxyProtocolPolicy = NonNullable<plugins.smartproxy.IRouteMatch['inboundProxyProtocol']>;
+const DCROUTER_CACHE_ID_HEADER = 'X-Dcrouter-Cached-Email-Id';
+const ACCEPTED_EMAIL_SPOOL_INTERVAL_MS = 60_000;
+const ACCEPTED_EMAIL_RETRY_DELAY_MS = 5 * 60_000;
+const ACCEPTED_EMAIL_QUEUE_LEASE_MS = 30 * 60_000;
+const ACCEPTED_EMAIL_SPOOL_BATCH_SIZE = 25;
+const ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS = 30_000;
+
+type TSmartMtaQueueItemLike = {
+  processingResult?: {
+    headers?: Record<string, string>;
+    email?: { headers?: Record<string, string> };
+  };
+  status?: 'pending' | 'processing' | 'queued' | 'delivered' | 'failed' | 'deferred';
+  attempts?: number;
+  nextAttempt?: Date;
+  lastError?: string;
+};
+
+type TStoredCachedEmailEnvelopeAddress = {
+  address: string;
+  args?: Record<string, string>;
+};
+
+type TStoredCachedEmailSession = {
+  id?: string;
+  clientHostname?: string;
+  remoteAddress?: string;
+  secure?: boolean;
+  authenticated?: boolean;
+  user?: IExtendedSmtpSession['user'];
+  envelope?: {
+    mailFrom?: TStoredCachedEmailEnvelopeAddress;
+    rcptTo?: TStoredCachedEmailEnvelopeAddress[];
+  };
+};
+
+type TStoredCachedEmailRouteData = {
+  session?: TStoredCachedEmailSession;
+};
 
 export interface IDcRouterOptions {
   /** Base directory for all dcrouter data. Defaults to ~/.serve.zone/dcrouter */
@@ -280,6 +323,11 @@ export class DcRouter {
   private remoteIngressHubLifecycleChain: Promise<void> = Promise.resolve();
   private smartProxyLifecycleChain: Promise<void> = Promise.resolve();
   private emailLifecycleChain: Promise<void> = Promise.resolve();
+  private acceptedEmailSpoolTimer?: ReturnType<typeof setInterval> & { unref?: () => void };
+  private acceptedEmailSpoolRun?: Promise<void>;
+  private acceptedEmailSpoolProcessing = false;
+  private acceptedEmailSpoolStopping = false;
+  private acceptedEmailQueueUpdatePromises = new Set<Promise<void>>();
   private remoteIngressHubStopping = false;
   private remoteIngressHubGeneration = 0;
 
@@ -680,12 +728,10 @@ export class DcRouter {
       );
     }
 
-    // Email Server: optional, depends on SmartProxy
-    if (this.options.dbConfig?.enabled !== false || this.options.emailConfig) {
+    // Email Server: optional, depends on SmartProxy and durable DB persistence.
+    if (this.options.dbConfig?.enabled !== false) {
       const emailServiceDeps = ['SmartProxy', 'MetricsManager'];
-      if (this.options.dbConfig?.enabled !== false) {
-        emailServiceDeps.push('EmailDomainManager');
-      }
+      emailServiceDeps.push('EmailDomainManager');
       this.serviceManager.addService(
         new plugins.taskbuffer.Service('EmailServer')
           .optional()
@@ -706,6 +752,8 @@ export class DcRouter {
           })
           .withRetry({ maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30_000 }),
       );
+    } else if (this.options.emailConfig) {
+      logger.log('warn', 'EmailServer: dbConfig.enabled=false, skipping SMTP startup because accepted email requires durable DB persistence');
     }
 
     // DNS Server: optional, depends on SmartProxy
@@ -713,7 +761,7 @@ export class DcRouter {
       this.serviceManager.addService(
         new plugins.taskbuffer.Service('DnsServer')
           .optional()
-          .dependsOn('SmartProxy', ...((this.options.dbConfig?.enabled !== false || this.options.emailConfig) ? ['EmailServer'] : []))
+          .dependsOn('SmartProxy', ...((this.options.dbConfig?.enabled !== false) ? ['EmailServer'] : []))
           .withStart(async () => {
             await this.setupDnsWithSocketHandler();
           })
@@ -1158,9 +1206,11 @@ export class DcRouter {
     logger.log('info', `Found ${this.seedConfigRoutes.length} routes in config`);
 
     this.seedEmailRoutes = [];
-    if (this.options.emailConfig) {
+    if (this.options.emailConfig && this.options.dbConfig?.enabled !== false) {
       this.seedEmailRoutes = this.generateEmailRoutes(this.options.emailConfig);
       logger.log('debug', 'Email routes generated', { routes: JSON.stringify(this.seedEmailRoutes) });
+    } else if (this.options.emailConfig) {
+      logger.log('warn', 'Email routes skipped because dbConfig.enabled=false and SMTP acceptance requires durable DB persistence');
     }
 
     this.seedDnsRoutes = [];
@@ -1395,6 +1445,12 @@ export class DcRouter {
       logger.log('info', `Creating SmartProxy instance: routes=${smartProxyConfig.routes?.length}, acme=${smartProxyConfig.acme?.enabled}, certProvisionFunction=${!!smartProxyConfig.certProvisionFunction}`);
       
       const smartProxy = new plugins.smartproxy.SmartProxy(smartProxyConfig);
+      smartProxy.registerChallengeProvider(
+        'smartchallenge',
+        new plugins.smartchallenge.SmartChallengeProvider({
+          challengeTypes: [new plugins.smartchallenge.WaitChallengeType()],
+        }),
+      );
       this.smartProxy = smartProxy;
       
       // Set up event listeners
@@ -1686,7 +1742,7 @@ export class DcRouter {
           
         case 465: // SMTPS
           routeName = 'smtps-route';
-          tlsMode = 'terminate'; // Terminate TLS and re-encrypt to email server
+          tlsMode = 'passthrough'; // Implicit TLS is handled by the email server backend
           break;
           
         default:
@@ -1723,9 +1779,11 @@ export class DcRouter {
 
       let action: any = {
         type: 'forward',
+        sendProxyProtocol: true,
         targets: [{
           host: 'localhost', // Forward to internal email server
-          port: internalPort
+          port: internalPort,
+          sendProxyProtocol: true,
         }],
         tls: {
           mode: tlsMode as any
@@ -1808,6 +1866,9 @@ export class DcRouter {
   }
 
   private getCurrentGeneratedEmailRouteNames(): Set<string> {
+    if (this.options.dbConfig?.enabled === false) {
+      return new Set();
+    }
     const sourceRoutes = this.seedEmailRoutes.length > 0
       ? this.seedEmailRoutes
       : this.options.emailConfig
@@ -1882,7 +1943,7 @@ export class DcRouter {
     targetHost: string,
     targetPort: number,
   ): NonNullable<plugins.smartproxy.IRouteConfig['action']['socketHandler']> {
-    return (clientSocket) => {
+    return (clientSocket, context) => {
       let backendSocket: plugins.net.Socket | undefined;
       let connectTimeout: ReturnType<typeof setTimeout> & { unref?: () => void };
       let cleanupDone = false;
@@ -1917,8 +1978,20 @@ export class DcRouter {
       backendSocket = plugins.net.connect(targetPort, targetHost, () => {
         clearTimeout(connectTimeout);
         backendSocket?.setTimeout(300_000);
-        clientSocket.pipe(backendSocket!);
-        backendSocket!.pipe(clientSocket);
+        const proxyHeader = this.createProxyProtocolV1Header(
+          context?.clientIp,
+          targetHost,
+          0,
+          targetPort,
+        );
+        if (!proxyHeader) {
+          cleanup();
+          return;
+        }
+        backendSocket!.write(proxyHeader, () => {
+          clientSocket.pipe(backendSocket!);
+          backendSocket!.pipe(clientSocket);
+        });
       });
       backendSocket.setTimeout(30_000);
       backendSocket.on('timeout', cleanup);
@@ -1928,6 +2001,32 @@ export class DcRouter {
     };
   }
 
+  private createProxyProtocolV1Header(
+    sourceIp: string | undefined,
+    destinationIp: string,
+    sourcePort: number,
+    destinationPort: number,
+  ): string | undefined {
+    if (!sourceIp || !plugins.net.isIP(sourceIp)) {
+      logger.log('warn', `Cannot create email PROXY protocol header for invalid source IP: ${sourceIp || 'unknown'}`);
+      return undefined;
+    }
+    const sourceFamily = plugins.net.isIP(sourceIp);
+    const destinationAddress = destinationIp === 'localhost' || destinationIp === '127.0.0.1' || destinationIp === '::1'
+      ? sourceFamily === 6 ? '::1' : '127.0.0.1'
+      : destinationIp;
+    const destinationFamily = plugins.net.isIP(destinationAddress);
+    if (!destinationFamily) {
+      logger.log('warn', `Cannot create email PROXY protocol header for invalid destination IP: ${destinationIp}`);
+      return undefined;
+    }
+    if (sourceFamily !== destinationFamily) {
+      return undefined;
+    }
+    const protocol = sourceFamily === 6 ? 'TCP6' : 'TCP4';
+    return `PROXY ${protocol} ${sourceIp} ${destinationAddress} ${sourcePort} ${destinationPort}\r\n`;
+  }
+
   private hydrateStoredRouteForRuntime(storedRoute: IRoute): plugins.smartproxy.IRouteConfig | undefined {
     const routeName = storedRoute.route.name || '';
     const isDohRoute = storedRoute.origin === 'dns'
@@ -2068,6 +2167,9 @@ export class DcRouter {
     if (!this.options.emailConfig) {
       throw new Error('Email configuration is required for unified email handling');
     }
+    if (!this.dcRouterDb?.isReady()) {
+      throw new Error('DcRouterDb is required for email acceptance');
+    }
 
     // Apply port mapping if behind SmartProxy
     const portMapping = this.options.emailPortConfig?.portMapping || {
@@ -2077,14 +2179,56 @@ export class DcRouter {
     };
     
     // Create config with mapped ports
+    const baseEmailConfig = this.options.emailConfig;
+    const configuredMessageDataHook = baseEmailConfig.hooks?.onMessageData;
+    const mappedEmailPorts = baseEmailConfig.ports.map(port => portMapping[port] || port + 10000);
+    const configuredSecurePort = baseEmailConfig.smtp?.securePort;
+    const defaultSecurePort = baseEmailConfig.ports.includes(465) ? 465 : undefined;
+    const securePortSource = configuredSecurePort ?? defaultSecurePort;
+    const mappedSecurePort = securePortSource === undefined
+      ? undefined
+      : mappedEmailPorts.includes(securePortSource) && !baseEmailConfig.ports.includes(securePortSource)
+        ? securePortSource
+        : portMapping[securePortSource] || securePortSource + 10000;
     const emailConfig: IUnifiedEmailServerOptions = await this.workAppMailManager.applyStoredIdentitiesToEmailConfig({
       ...this.options.emailConfig,
-      ports: this.options.emailConfig.ports.map(port => portMapping[port] || port + 10000),
+      ports: mappedEmailPorts,
       persistRoutes: this.options.emailConfig.persistRoutes ?? false,
       queue: {
-        storageType: 'disk',
-        persistentPath: plugins.path.join(this.resolvedPaths.dataDir, 'smartmta-queue'),
         ...this.options.emailConfig.queue,
+        storageType: 'memory',
+      },
+      smtp: {
+        ...baseEmailConfig.smtp,
+        ...(mappedSecurePort !== undefined
+          ? { securePort: mappedSecurePort }
+          : {}),
+        recipientValidation: true,
+        proxyProtocol: {
+          ...baseEmailConfig.smtp?.proxyProtocol,
+          required: true,
+          trustedIps: ['127.0.0.1', '::1'],
+        },
+      },
+      hooks: {
+        ...baseEmailConfig.hooks,
+        onMessageData: async (context) => {
+          const configuredDecision = configuredMessageDataHook
+            ? await configuredMessageDataHook(context)
+            : undefined;
+          if (configuredDecision && !configuredDecision.accepted) {
+            return configuredDecision;
+          }
+          const dcrouterDecision = await this.acceptSmartMtaMessage(
+            context,
+            configuredDecision ? configuredDecision.continueProcessing === true : true,
+          );
+          return {
+            ...dcrouterDecision,
+            smtpCode: configuredDecision?.smtpCode ?? dcrouterDecision.smtpCode,
+            smtpMessage: configuredDecision?.smtpMessage ?? dcrouterDecision.smtpMessage,
+          };
+        },
       },
     });
     
@@ -2114,58 +2258,450 @@ export class DcRouter {
       throw error;
     }
 
-    // Wire delivery events to MetricsManager and logger using smartmta's public queue APIs.
-    if (this.metricsManager) {
-      const getEnvelope = (item: { processingResult?: any; lastError?: string }) => {
-        const emailLike = item?.processingResult;
-        const from = emailLike?.from || emailLike?.email?.from || '';
-        const recipients = Array.isArray(emailLike?.to)
-          ? emailLike.to
-          : Array.isArray(emailLike?.email?.to)
-            ? emailLike.email.to
-            : [];
-        return {
-          from,
-          recipients: recipients.filter(Boolean),
-        };
-      };
-      const updateQueueSize = () => {
-        this.metricsManager!.updateQueueSize(emailServer.getQueueStats().queueSize);
-      };
-
-      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemEnqueued', (item: any) => {
-        const envelope = getEnvelope(item);
-        this.metricsManager!.trackEmailReceived(envelope.from);
-        updateQueueSize();
-        logger.log('info', `Email queued: ${envelope.from} → ${envelope.recipients.join(', ') || 'unknown'}`, { zone: 'email' });
+    try {
+      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemEnqueued', (item: TSmartMtaQueueItemLike) => {
+        this.trackAcceptedEmailQueueUpdate(item, 'queued', 'Unable to update accepted email after queue enqueue');
       });
-      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDelivered', (item: any) => {
-        const envelope = getEnvelope(item);
-        this.metricsManager!.trackEmailSent(envelope.recipients[0]);
-        updateQueueSize();
-        logger.log('info', `Email delivered to ${envelope.recipients.join(', ') || 'unknown'}`, { zone: 'email' });
+      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDelivered', (item: TSmartMtaQueueItemLike) => {
+        this.trackAcceptedEmailQueueUpdate(item, 'delivered', 'Unable to mark accepted email delivered');
       });
-      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemFailed', (item: any) => {
-        const envelope = getEnvelope(item);
-        this.metricsManager!.trackEmailFailed(envelope.recipients[0], item?.lastError);
-        updateQueueSize();
-        logger.log('warn', `Email delivery failed to ${envelope.recipients.join(', ') || 'unknown'}: ${item?.lastError || 'unknown error'}`, { zone: 'email' });
+      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDeferred', (item: TSmartMtaQueueItemLike) => {
+        this.trackAcceptedEmailQueueUpdate(item, 'queued', 'Unable to defer accepted email');
       });
-      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDeferred', () => {
-        updateQueueSize();
+      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemFailed', (item: TSmartMtaQueueItemLike) => {
+        this.trackAcceptedEmailQueueUpdate(item, 'failed', 'Unable to mark accepted email failed');
       });
-      this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemRemoved', () => {
+
+      // Wire delivery events to MetricsManager and logger using smartmta's public queue APIs.
+      if (this.metricsManager) {
+        const getEnvelope = (item: { processingResult?: any; lastError?: string }) => {
+          const emailLike = item?.processingResult;
+          const from = emailLike?.from || emailLike?.email?.from || '';
+          const recipients = Array.isArray(emailLike?.to)
+            ? emailLike.to
+            : Array.isArray(emailLike?.email?.to)
+              ? emailLike.email.to
+              : [];
+          return {
+            from,
+            recipients: recipients.filter(Boolean),
+          };
+        };
+        const updateQueueSize = () => {
+          this.metricsManager!.updateQueueSize(emailServer.getQueueStats().queueSize);
+        };
+
+        this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemEnqueued', (item: any) => {
+          const envelope = getEnvelope(item);
+          this.metricsManager!.trackEmailReceived(envelope.from);
+          updateQueueSize();
+          logger.log('info', `Email queued: ${envelope.from} → ${envelope.recipients.join(', ') || 'unknown'}`, { zone: 'email' });
+        });
+        this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDelivered', (item: any) => {
+          const envelope = getEnvelope(item);
+          this.metricsManager!.trackEmailSent(envelope.recipients[0]);
+          updateQueueSize();
+          logger.log('info', `Email delivered to ${envelope.recipients.join(', ') || 'unknown'}`, { zone: 'email' });
+        });
+        this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemFailed', (item: any) => {
+          const envelope = getEnvelope(item);
+          this.metricsManager!.trackEmailFailed(envelope.recipients[0], item?.lastError);
+          updateQueueSize();
+          logger.log('warn', `Email delivery failed to ${envelope.recipients.join(', ') || 'unknown'}: ${item?.lastError || 'unknown error'}`, { zone: 'email' });
+        });
+        this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemDeferred', () => {
+          updateQueueSize();
+        });
+        this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemRemoved', () => {
+          updateQueueSize();
+        });
+        this.addEmailEventSubscription(emailServer, 'bounceProcessed', () => {
+          this.metricsManager!.trackEmailBounced();
+          logger.log('warn', 'Email bounce processed', { zone: 'email' });
+        });
         updateQueueSize();
-      });
-      this.addEmailEventSubscription(emailServer, 'bounceProcessed', () => {
-        this.metricsManager!.trackEmailBounced();
-        logger.log('warn', 'Email bounce processed', { zone: 'email' });
-      });
-      updateQueueSize();
+      }
+
+      await this.recoverQueuedAcceptedEmails();
+      this.startAcceptedEmailSpoolProcessor();
+    } catch (error: unknown) {
+      this.acceptedEmailSpoolStopping = true;
+      this.clearAcceptedEmailSpoolTimer();
+      try {
+        await emailServer.stop();
+      } catch (stopError: unknown) {
+        logger.log('warn', `Error cleaning up failed UnifiedEmailServer setup: ${(stopError as Error).message}`);
+      }
+      await this.stopAcceptedEmailSpoolProcessor();
+      await this.drainAcceptedEmailQueueUpdates();
+      this.clearEmailEventSubscriptions();
+      if (this.emailServer === emailServer) {
+        this.emailServer = undefined;
+      }
+      throw error;
     }
 
     logger.log('info', `Email server started on ports: ${emailConfig.ports.join(', ')}`);
   }
+
+  private async acceptSmartMtaMessage(
+    context: IMessageAcceptanceContext,
+    processAfterAccept = true,
+  ): Promise<IMessageAcceptanceDecision> {
+    if (!this.dcRouterDb?.isReady()) {
+      throw new Error('DcRouterDb is not available for email acceptance');
+    }
+    this.throwIfMessageAcceptanceAborted(context.abortSignal);
+
+    const rawMessage = context.rawMessage;
+    const session = context.session;
+    const envelope = session.envelope;
+    const envelopeRecipients = Array.isArray(envelope.rcptTo)
+      ? envelope.rcptTo.map((recipient) => recipient.address).filter(Boolean)
+      : [];
+    const email = context.email;
+    const headers = email.headers;
+
+    const cachedEmail = CachedEmail.createNew();
+    this.removeHeader(email.headers, DCROUTER_CACHE_ID_HEADER);
+    email.headers[DCROUTER_CACHE_ID_HEADER] = cachedEmail.id;
+    cachedEmail.messageId = headers['Message-ID'] || headers['message-id'] || cachedEmail.id;
+    cachedEmail.from = envelope.mailFrom?.address || email.from || '';
+    cachedEmail.to = envelopeRecipients.length > 0
+      ? envelopeRecipients
+      : Array.isArray(email.to) ? email.to : [];
+    cachedEmail.cc = Array.isArray(email.cc) ? email.cc : [];
+    cachedEmail.bcc = Array.isArray(email.bcc) ? email.bcc : [];
+    cachedEmail.subject = email.subject || '';
+    cachedEmail.rawContent = this.setDcRouterCacheIdHeader(rawMessage.toString('utf8'), cachedEmail.id);
+    cachedEmail.status = 'pending';
+    cachedEmail.nextAttempt = new Date();
+    cachedEmail.routeData = JSON.stringify({
+      acceptedAt: new Date().toISOString(),
+      session: {
+        id: session.id,
+        remoteAddress: session.remoteAddress,
+        clientHostname: session.clientHostname,
+        secure: !!session.secure,
+        authenticated: !!session.authenticated,
+        user: session.user,
+        envelope,
+      },
+    });
+    cachedEmail.updateSenderDomain();
+    await cachedEmail.save();
+    if (context.abortSignal?.aborted) {
+      cachedEmail.markFailed('Message acceptance aborted before SMTP success');
+      await cachedEmail.save();
+      throw new Error('Message acceptance aborted before SMTP success');
+    }
+
+    if (processAfterAccept) {
+      this.runAcceptedEmailSpoolProcessor();
+    } else {
+      cachedEmail.markDelivered();
+      await cachedEmail.save();
+    }
+
+    return {
+      accepted: true,
+      smtpCode: 250,
+      smtpMessage: '2.0.0 Message accepted for delivery',
+      continueProcessing: false,
+    };
+  }
+
+  private setDcRouterCacheIdHeader(rawContent: string, cachedEmailId: string): string {
+    const headerRegex = new RegExp(`^${DCROUTER_CACHE_ID_HEADER}:.*(?:\r?\n[\t ].*)*\r?\n?`, 'gim');
+    const sanitizedContent = rawContent.replace(headerRegex, '');
+    return `${DCROUTER_CACHE_ID_HEADER}: ${cachedEmailId}\r\n${sanitizedContent}`;
+  }
+
+  private async processAcceptedCachedEmail(
+    cachedEmail: CachedEmail,
+    emailData: Email | plugins.buffer.Buffer,
+    session: IExtendedSmtpSession,
+    emailServer: UnifiedEmailServer,
+  ): Promise<void> {
+    cachedEmail.status = 'processing';
+    cachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
+    await cachedEmail.save();
+
+    try {
+      await emailServer.processEmailByMode(emailData, session);
+      if (session.matchedRoute?.action.type === 'forward') {
+        cachedEmail.markDelivered();
+      } else {
+        const currentCachedEmail = await CachedEmail.findById(cachedEmail.id) || cachedEmail;
+        if (this.isCachedEmailTerminal(currentCachedEmail)) {
+          return;
+        }
+        currentCachedEmail.status = 'queued';
+        currentCachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
+        await currentCachedEmail.save();
+        return;
+      }
+      await cachedEmail.save();
+    } catch (error: unknown) {
+      cachedEmail.scheduleRetry(ACCEPTED_EMAIL_RETRY_DELAY_MS);
+      cachedEmail.lastError = (error as Error).message;
+      await cachedEmail.save();
+      logger.log('warn', `Accepted email ${cachedEmail.id} deferred after SmartMTA handoff failure: ${(error as Error).message}`);
+    }
+  }
+
+  private startAcceptedEmailSpoolProcessor(): void {
+    this.clearAcceptedEmailSpoolTimer();
+    this.acceptedEmailSpoolStopping = false;
+    const runProcessor = () => {
+      this.runAcceptedEmailSpoolProcessor();
+    };
+    this.acceptedEmailSpoolTimer = setInterval(
+      runProcessor,
+      ACCEPTED_EMAIL_SPOOL_INTERVAL_MS,
+    ) as ReturnType<typeof setInterval> & { unref?: () => void };
+    this.acceptedEmailSpoolTimer.unref?.();
+    runProcessor();
+  }
+
+  private clearAcceptedEmailSpoolTimer(): void {
+    if (this.acceptedEmailSpoolTimer) {
+      clearInterval(this.acceptedEmailSpoolTimer);
+      this.acceptedEmailSpoolTimer = undefined;
+    }
+  }
+
+  private async stopAcceptedEmailSpoolProcessor(): Promise<void> {
+    this.acceptedEmailSpoolStopping = true;
+    this.clearAcceptedEmailSpoolTimer();
+    const spoolRun = this.acceptedEmailSpoolRun;
+    if (spoolRun) {
+      const settled = await this.waitForPromiseToSettleWithTimeout(
+        spoolRun,
+        ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS,
+      );
+      if (!settled) {
+        logger.log('warn', 'Timed out waiting for accepted email spool processing to stop');
+      }
+    }
+  }
+
+  private runAcceptedEmailSpoolProcessor(): void {
+    if (this.acceptedEmailSpoolRun) {
+      return;
+    }
+    const run = this.processAcceptedEmailSpool().catch((error) => {
+      logger.log('warn', `Accepted email spool processing failed: ${(error as Error).message}`);
+    });
+    this.acceptedEmailSpoolRun = run;
+    void run.finally(() => {
+      if (this.acceptedEmailSpoolRun === run) {
+        this.acceptedEmailSpoolRun = undefined;
+      }
+    });
+  }
+
+  private async processAcceptedEmailSpool(): Promise<void> {
+    const emailServer = this.emailServer;
+    if (this.acceptedEmailSpoolProcessing || !emailServer || !this.dcRouterDb?.isReady()) {
+      return;
+    }
+    this.acceptedEmailSpoolProcessing = true;
+    try {
+      const cachedEmails = await CachedEmail.findPendingForDelivery(ACCEPTED_EMAIL_SPOOL_BATCH_SIZE);
+      for (const cachedEmail of cachedEmails) {
+        if (this.acceptedEmailSpoolStopping || this.emailServer !== emailServer) {
+          break;
+        }
+        const session = this.buildCachedEmailSession(cachedEmail);
+        const rawMessage = plugins.buffer.Buffer.from(cachedEmail.rawContent || '', 'utf8');
+        await this.processAcceptedCachedEmail(cachedEmail, rawMessage, session, emailServer);
+      }
+    } finally {
+      this.acceptedEmailSpoolProcessing = false;
+    }
+  }
+
+  private buildCachedEmailSession(cachedEmail: CachedEmail): IExtendedSmtpSession {
+    const routeData = this.parseCachedEmailRouteData(cachedEmail);
+    const storedSession = routeData.session || {};
+    const storedEnvelope = storedSession.envelope || {};
+    const storedRcptTo = Array.isArray(storedEnvelope.rcptTo) && storedEnvelope.rcptTo.length > 0
+      ? storedEnvelope.rcptTo
+      : cachedEmail.to.map((address) => ({ address, args: {} }));
+    const rcptTo = storedRcptTo
+      .filter((recipient) => !!recipient.address)
+      .map((recipient) => ({ address: recipient.address, args: recipient.args || {} }));
+    const mailFrom = storedEnvelope.mailFrom
+      ? { address: storedEnvelope.mailFrom.address, args: storedEnvelope.mailFrom.args || {} }
+      : { address: cachedEmail.from || '', args: {} };
+    const session = {
+      id: `${storedSession.id || cachedEmail.id}-replay-${Date.now()}`,
+      state: 'DATA' as unknown as IExtendedSmtpSession['state'],
+      clientHostname: storedSession.clientHostname || '',
+      mailFrom: mailFrom.address,
+      rcptTo: rcptTo.map((recipient) => recipient.address),
+      emailData: cachedEmail.rawContent || '',
+      useTLS: !!storedSession.secure,
+      connectionEnded: false,
+      remoteAddress: storedSession.remoteAddress || '127.0.0.1',
+      secure: !!storedSession.secure,
+      authenticated: !!storedSession.authenticated,
+      envelope: {
+        mailFrom,
+        rcptTo,
+      },
+    } as IExtendedSmtpSession;
+    if (storedSession.user) {
+      session.user = storedSession.user;
+    }
+    return session;
+  }
+
+  private parseCachedEmailRouteData(cachedEmail: CachedEmail): TStoredCachedEmailRouteData {
+    try {
+      return cachedEmail.routeData ? JSON.parse(cachedEmail.routeData) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  private async updateAcceptedEmailFromQueueItem(
+    item: TSmartMtaQueueItemLike,
+    status: 'queued' | 'delivered' | 'failed',
+  ): Promise<void> {
+    const cachedEmailId = this.getCachedEmailIdFromQueueItem(item);
+    if (!cachedEmailId || !this.dcRouterDb?.isReady()) {
+      return;
+    }
+    const cachedEmail = await CachedEmail.findById(cachedEmailId);
+    if (!cachedEmail) {
+      return;
+    }
+    if (this.isCachedEmailTerminal(cachedEmail) && status !== 'delivered') {
+      return;
+    }
+    cachedEmail.attempts = Math.max(cachedEmail.attempts || 0, item.attempts || 0);
+    if (status === 'delivered') {
+      cachedEmail.markDelivered();
+    } else if (status === 'failed') {
+      cachedEmail.markFailed(item.lastError || 'SmartMTA delivery failed');
+    } else {
+      cachedEmail.status = 'queued';
+      cachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
+    }
+    await cachedEmail.save();
+  }
+
+  private trackAcceptedEmailQueueUpdate(
+    item: TSmartMtaQueueItemLike,
+    status: 'queued' | 'delivered' | 'failed',
+    failureMessage: string,
+  ): void {
+    const updatePromise = this.updateAcceptedEmailFromQueueItem(item, status).catch((error) => {
+      logger.log('warn', `${failureMessage}: ${(error as Error).message}`);
+    });
+    this.acceptedEmailQueueUpdatePromises.add(updatePromise);
+    void updatePromise.finally(() => {
+      this.acceptedEmailQueueUpdatePromises.delete(updatePromise);
+    });
+  }
+
+  private async drainAcceptedEmailQueueUpdates(): Promise<void> {
+    const queueUpdates = [...this.acceptedEmailQueueUpdatePromises];
+    if (queueUpdates.length === 0) {
+      return;
+    }
+    const settled = await this.waitForPromiseToSettleWithTimeout(
+      Promise.allSettled(queueUpdates).then(() => undefined),
+      ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS,
+    );
+    if (!settled) {
+      for (const queueUpdate of queueUpdates) {
+        this.acceptedEmailQueueUpdatePromises.delete(queueUpdate);
+      }
+      logger.log('warn', `Timed out waiting for ${queueUpdates.length} accepted email queue update(s) to settle`);
+    }
+  }
+
+  private async waitForPromiseToSettleWithTimeout(
+    promise: Promise<unknown>,
+    timeoutMs: number,
+  ): Promise<boolean> {
+    let timeout: (ReturnType<typeof setTimeout> & { unref?: () => void }) | undefined;
+    return await new Promise<boolean>((resolve) => {
+      let settled = false;
+      const settle = (didSettle: boolean) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        resolve(didSettle);
+      };
+      timeout = setTimeout(() => settle(false), timeoutMs) as ReturnType<typeof setTimeout> & { unref?: () => void };
+      timeout.unref?.();
+      promise.then(
+        () => settle(true),
+        () => settle(true),
+      );
+    });
+  }
+
+  private async recoverQueuedAcceptedEmails(): Promise<void> {
+    while (true) {
+      const queuedEmails = await CachedEmail.findQueuedForRecovery(ACCEPTED_EMAIL_SPOOL_BATCH_SIZE);
+      if (queuedEmails.length === 0) {
+        return;
+      }
+      for (const queuedEmail of queuedEmails) {
+        if (this.isCachedEmailTerminal(queuedEmail)) {
+          continue;
+        }
+        queuedEmail.status = 'pending';
+        queuedEmail.nextAttempt = new Date();
+        await queuedEmail.save();
+      }
+      if (queuedEmails.length < ACCEPTED_EMAIL_SPOOL_BATCH_SIZE) {
+        return;
+      }
+    }
+  }
+
+  private isCachedEmailTerminal(cachedEmail: CachedEmail): boolean {
+    return cachedEmail.status === 'delivered' || cachedEmail.status === 'failed';
+  }
+
+  private getCachedEmailIdFromQueueItem(item: TSmartMtaQueueItemLike): string | undefined {
+    return this.getHeaderValue(item.processingResult?.headers, DCROUTER_CACHE_ID_HEADER)
+      || this.getHeaderValue(item.processingResult?.email?.headers, DCROUTER_CACHE_ID_HEADER);
+  }
+
+  private getHeaderValue(headers: Record<string, string> | undefined, headerName: string): string | undefined {
+    if (!headers) {
+      return undefined;
+    }
+    const normalizedHeaderName = headerName.toLowerCase();
+    const matchingHeaderName = Object.keys(headers).find((key) => key.toLowerCase() === normalizedHeaderName);
+    return matchingHeaderName ? headers[matchingHeaderName] : undefined;
+  }
+
+  private removeHeader(headers: Record<string, string>, headerName: string): void {
+    const normalizedHeaderName = headerName.toLowerCase();
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === normalizedHeaderName) {
+        delete headers[key];
+      }
+    }
+  }
+
+  private throwIfMessageAcceptanceAborted(abortSignal: AbortSignal | undefined): void {
+    if (abortSignal?.aborted) {
+      throw new Error('Message acceptance aborted before SMTP success');
+    }
+  }
   
   /**
    * Update the unified email configuration
@@ -2232,10 +2768,18 @@ export class DcRouter {
     try {
       // Stop the unified email server which contains all components
       if (this.emailServer) {
-        this.clearEmailEventSubscriptions();
-        await this.emailServer.stop();
-        logger.log('info', 'Unified email server stopped');
+        const emailServer = this.emailServer;
         this.emailServer = undefined;
+        this.acceptedEmailSpoolStopping = true;
+        this.clearAcceptedEmailSpoolTimer();
+        try {
+          await emailServer.stop();
+        } finally {
+          await this.stopAcceptedEmailSpoolProcessor();
+          await this.drainAcceptedEmailQueueUpdates();
+          this.clearEmailEventSubscriptions();
+        }
+        logger.log('info', 'Unified email server stopped');
       }
       
       logger.log('info', 'All unified email components stopped');