@push.rocks/smartmta 7.0.0 → 8.0.0

package/ts/mail/delivery/classes.delivery.system.ts

@@ -6,10 +6,20 @@ import {
   SecurityLogLevel,
   SecurityEventType
 } from '../../security/index.js';
-import { UnifiedDeliveryQueue, type IQueueItem } from './classes.delivery.queue.js';
+import {
+  UnifiedDeliveryQueue,
+  type IQueueItem,
+  type IRecipientPermanentFailure,
+} from './classes.delivery.queue.js';
 import { Email } from '../core/classes.email.js';
 import type { UnifiedEmailServer } from '../routing/classes.unified.email.server.js';
-import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
+import { SmtpDeliveryError } from '../../security/classes.rustsecuritybridge.js';
+import type {
+  ISmtpRecipientResult,
+  ISmtpSendResult,
+} from '../../security/classes.rustsecuritybridge.js';
+import type { ISmtpTransactionAttempt } from './interfaces.js';
+import { callObserverSafely, emitSafely } from './functions.safe-observers.js';
 
 const dns = plugins.dns;
 
@@ -100,9 +110,16 @@ export interface IDeliveryStats {
 /**
  * Handles delivery for all email processing modes
  */
+type TResolvedMultiModeDeliveryOptions = Omit<
+  Required<IMultiModeDeliveryOptions>,
+  'bounceHandler'
+> & {
+  bounceHandler?: NonNullable<IMultiModeDeliveryOptions['bounceHandler']>;
+};
+
 export class MultiModeDeliverySystem extends EventEmitter {
   private queue: UnifiedDeliveryQueue;
-  private options: Required<IMultiModeDeliveryOptions>;
+  private options: TResolvedMultiModeDeliveryOptions;
   private stats: IDeliveryStats;
   private deliveryTimes: number[] = [];
   private activeDeliveries: Set<string> = new Set();
@@ -112,6 +129,8 @@ export class MultiModeDeliverySystem extends EventEmitter {
   private rateLimitLastCheck: number = Date.now();
   private rateLimitCounter: number = 0;
   private emailServer?: UnifiedEmailServer;
+  private bounceDrainTimer?: NodeJS.Timeout;
+  private bounceDrainPromise?: Promise<void>;
   
   /**
    * Create a new multi-mode delivery system
@@ -145,7 +164,7 @@ export class MultiModeDeliverySystem extends EventEmitter {
       globalRateLimit: options.globalRateLimit || 100, // 100 emails per minute
       perPatternRateLimit: options.perPatternRateLimit || {},
       processBounces: options.processBounces !== false, // Default to true
-      bounceHandler: options.bounceHandler || null,
+      bounceHandler: options.bounceHandler,
       onDeliveryStart: options.onDeliveryStart || (async () => {}),
       onDeliverySuccess: options.onDeliverySuccess || (async () => {}),
       onDeliveryFailed: options.onDeliveryFailed || (async () => {})
@@ -181,7 +200,169 @@ export class MultiModeDeliverySystem extends EventEmitter {
     // Set up event listeners
     this.queue.on('itemsReady', this.processItems.bind(this));
   }
-  
+
+  private createEmailForRecipients(email: Email, recipients: string[]): Email {
+    const recipientSet = new Set(recipients.map((recipient) => recipient.toLowerCase()));
+    return new Email({
+      ...email.toEmailOptions(),
+      to: email.to.filter((recipient) => recipientSet.has(recipient.toLowerCase())),
+      cc: (email.cc || []).filter((recipient) => recipientSet.has(recipient.toLowerCase())),
+      bcc: (email.bcc || []).filter((recipient) => recipientSet.has(recipient.toLowerCase())),
+    })
+      .setMessageId(email.getMessageId())
+      .setEnvelopeFrom(email.getEnvelopeFrom());
+  }
+
+  private contextualizeSmtpError(
+    errorArg: unknown,
+    recipients: string[],
+    recipientDomain?: string,
+  ): SmtpDeliveryError {
+    const error = SmtpDeliveryError.from(errorArg);
+    return new SmtpDeliveryError({
+      message: error.message,
+      errorType: error.errorType,
+      retryable: error.retryable,
+      ...(error.smtpCode !== undefined ? { smtpCode: error.smtpCode } : {}),
+      phase: error.phase,
+      transactionLog: error.transactionLog,
+      recipients,
+      recipientResults: error.recipientResults,
+      ...(recipientDomain ? { recipientDomain } : {}),
+    }, error);
+  }
+
+  private async persistSmtpAttempt(optionsArg: {
+    item: IQueueItem;
+    targetHost: string;
+    targetPort: number;
+    recipients: string[];
+    recipientDomain?: string;
+    startedAt: Date;
+    result?: ISmtpSendResult;
+    error?: SmtpDeliveryError;
+  }): Promise<ISmtpTransactionAttempt> {
+    const completedAt = new Date();
+    const error = optionsArg.error;
+    const attempt: ISmtpTransactionAttempt = {
+      id: plugins.uuid.v4(),
+      queueItemId: optionsArg.item.id,
+      queueAttempt: optionsArg.item.attempts,
+      targetHost: optionsArg.targetHost,
+      targetPort: optionsArg.targetPort,
+      ...(optionsArg.recipientDomain
+        ? { recipientDomain: optionsArg.recipientDomain }
+        : {}),
+      recipients: [...optionsArg.recipients],
+      startedAt: optionsArg.startedAt.toISOString(),
+      completedAt: completedAt.toISOString(),
+      durationMs: completedAt.getTime() - optionsArg.startedAt.getTime(),
+      outcome: error ? 'failed' : 'succeeded',
+      retryable: error?.retryable ?? false,
+      ...(error?.errorType ? { errorType: error.errorType } : {}),
+      ...(error?.smtpCode !== undefined ? { smtpCode: error.smtpCode } : {}),
+      recipientResults: error?.recipientResults || optionsArg.result?.recipientResults,
+      ...(error ? { failurePhase: error.phase, error: error.message } : {}),
+      transcript: error?.transactionLog || optionsArg.result?.transactionLog || [],
+    };
+    await this.queue.appendSmtpTransaction(optionsArg.item.id, attempt);
+    await emitSafely(this, 'smtpTransactionCompleted', attempt);
+    return attempt;
+  }
+
+  private splitRecipientResults(
+    results: ISmtpRecipientResult[] | undefined,
+    rejectedFallback: string[] = [],
+  ): { accepted: string[]; permanent: ISmtpRecipientResult[]; transient: string[] } {
+    if (!results || results.length === 0) {
+      return { accepted: [], permanent: [], transient: [...rejectedFallback] };
+    }
+    const representedRecipients = new Set(
+      results.map((result) => result.recipient.toLowerCase()),
+    );
+    return {
+      accepted: results.filter((result) => result.accepted).map((result) => result.recipient),
+      permanent: results.filter(
+        (result) => !result.accepted && result.responseCode >= 500,
+      ),
+      transient: [
+        ...results
+          .filter((result) => !result.accepted && result.responseCode < 500)
+          .map((result) => result.recipient),
+        ...rejectedFallback.filter(
+          (recipient) => !representedRecipients.has(recipient.toLowerCase()),
+        ),
+      ],
+    };
+  }
+
+  private async checkpointPermanentRecipientFailures(
+    item: IQueueItem,
+    results: ISmtpRecipientResult[],
+  ): Promise<string[]> {
+    const failures: IRecipientPermanentFailure[] = results.map((result) => ({
+      recipient: result.recipient,
+      smtpCode: result.responseCode,
+      smtpResponse: `SMTP recipient rejected with ${result.responseCode}`,
+    }));
+    const newlyTerminal = await this.queue.markRecipientsTerminal(item.id, failures);
+    if (newlyTerminal.length > 0 && this.running) {
+      void this.drainBounceOutbox();
+    }
+    return newlyTerminal;
+  }
+
+  /**
+   * Drain durable bounce work with one in-process flight. Custom handlers
+   * receive operationId and must use it for their own idempotency.
+   */
+  public async drainBounceOutbox(): Promise<void> {
+    if (this.bounceDrainPromise) return this.bounceDrainPromise;
+    const drain = (async () => {
+      if (!this.options.processBounces || !this.options.bounceHandler) return;
+      for (const { itemId, operation } of this.queue.listPendingBounceOperations()) {
+        const item = this.queue.getItem(itemId);
+        if (!item) continue;
+        const email = item.processingResult as Email;
+        try {
+          await this.options.bounceHandler.processSmtpFailure(
+            operation.recipient,
+            operation.smtpResponse,
+            {
+              operationId: operation.operationId,
+              sender: email.from,
+              originalEmailId: item.id,
+              headers: email.headers,
+              statusCode: String(operation.smtpCode),
+            },
+          );
+          await this.queue.markBounceOperationCompleted(itemId, operation.operationId);
+        } catch (error) {
+          logger.log(
+            'error',
+            `Bounce operation ${operation.operationId} failed: ${(error as Error).message}`,
+          );
+          try {
+            await this.queue.markBounceOperationFailed(
+              itemId,
+              operation.operationId,
+              (error as Error).message,
+            );
+          } catch (checkpointError) {
+            logger.log(
+              'error',
+              `Could not checkpoint failed bounce operation ${operation.operationId}: ${(checkpointError as Error).message}`,
+            );
+          }
+        }
+      }
+    })();
+    this.bounceDrainPromise = drain.finally(() => {
+      this.bounceDrainPromise = undefined;
+    });
+    return this.bounceDrainPromise;
+  }
+
   /**
    * Start the delivery system
    */
@@ -194,9 +375,12 @@ export class MultiModeDeliverySystem extends EventEmitter {
     }
     
     this.running = true;
-    
-    // Emit started event
-    this.emit('started');
+    await this.drainBounceOutbox();
+    this.bounceDrainTimer = setInterval(() => {
+      void this.drainBounceOutbox();
+    }, 30_000);
+
+    await emitSafely(this, 'started');
     logger.log('info', 'MultiModeDeliverySystem started successfully');
   }
   
@@ -212,6 +396,10 @@ export class MultiModeDeliverySystem extends EventEmitter {
     }
     
     this.running = false;
+    if (this.bounceDrainTimer) {
+      clearInterval(this.bounceDrainTimer);
+      this.bounceDrainTimer = undefined;
+    }
 
     // Clear throttle reset timer to prevent it firing after stop
     if (this.throttleResetTimer) {
@@ -241,8 +429,8 @@ export class MultiModeDeliverySystem extends EventEmitter {
       });
     }
     
-    // Emit stopped event
-    this.emit('stopped');
+    await this.bounceDrainPromise;
+    await emitSafely(this, 'stopped');
     logger.log('info', 'MultiModeDeliverySystem stopped successfully');
   }
   
@@ -267,33 +455,46 @@ export class MultiModeDeliverySystem extends EventEmitter {
       return;
     }
     
-    // Calculate how many more deliveries we can start
-    const availableSlots = this.options.concurrentDeliveries - this.activeDeliveries.size;
-    const itemsToProcess = items.slice(0, availableSlots);
-    
-    if (itemsToProcess.length === 0) {
-      return;
-    }
-    
-    logger.log('info', `Processing ${itemsToProcess.length} items for delivery`);
-    
-    // Process each item
-    for (const item of itemsToProcess) {
-      // Mark as processing
-      await this.queue.markProcessing(item.id);
-      
-      // Add to active deliveries
+    let startedDeliveries = 0;
+
+    for (const item of items) {
+      if (this.activeDeliveries.size >= this.options.concurrentDeliveries) break;
+      if (this.activeDeliveries.has(item.id)) continue;
+
+      // Reserve synchronously before the first await so overlapping queue events
+      // cannot dispatch the same item while its durable claim is in flight.
       this.activeDeliveries.add(item.id);
       this.stats.activeDeliveries = this.activeDeliveries.size;
-      
+
+      let claimed = false;
+      try {
+        claimed = await this.queue.markProcessing(item.id);
+      } catch (error) {
+        this.activeDeliveries.delete(item.id);
+        this.stats.activeDeliveries = this.activeDeliveries.size;
+        logger.log('error', `Failed to claim queue item ${item.id}: ${(error as Error).message}`);
+        continue;
+      }
+
+      if (!claimed) {
+        this.activeDeliveries.delete(item.id);
+        this.stats.activeDeliveries = this.activeDeliveries.size;
+        continue;
+      }
+
+      startedDeliveries++;
       // Deliver asynchronously
       this.deliverItem(item).catch(err => {
         logger.log('error', `Unhandled error in delivery: ${err.message}`);
       });
     }
+
+    if (startedDeliveries > 0) {
+      logger.log('info', `Processing ${startedDeliveries} items for delivery`);
+    }
     
     // Update statistics
-    this.emit('statsUpdated', this.stats);
+    await emitSafely(this, 'statsUpdated', this.stats);
   }
   
   /**
@@ -305,10 +506,10 @@ export class MultiModeDeliverySystem extends EventEmitter {
     
     try {
       // Call delivery start hook
-      await this.options.onDeliveryStart(item);
+      await callObserverSafely('delivery start hook', this.options.onDeliveryStart, item);
       
       // Emit delivery start event
-      this.emit('deliveryStart', item);
+      await emitSafely(this, 'deliveryStart', item);
       logger.log('info', `Starting delivery of item ${item.id}, mode: ${item.processingMode}`);
       
       // Choose the appropriate handler based on mode
@@ -331,8 +532,36 @@ export class MultiModeDeliverySystem extends EventEmitter {
           throw new Error(`Unknown processing mode: ${item.processingMode}`);
       }
       
-      // Mark as delivered
-      await this.queue.markDelivered(item.id);
+      // Built-in SMTP handlers checkpoint every recipient before returning.
+      // A partial success is terminal-success only when no recipient remains
+      // unresolved; all-permanent with no delivery is terminal failure.
+      if (result?.recipientDispositionManaged) {
+        const disposition = this.queue.getRecipientDisposition(item.id);
+        if (disposition.unresolved.length > 0) {
+          throw new SmtpDeliveryError({
+            message: `SMTP delivery left ${disposition.unresolved.length} recipient(s) unresolved`,
+            errorType: 'smtp_aggregate',
+            retryable: true,
+            phase: 'rcpt_to',
+            transactionLog: [],
+            recipients: disposition.unresolved,
+          });
+        }
+        if (disposition.delivered.length === 0 && disposition.permanentFailures.length > 0) {
+          throw new SmtpDeliveryError({
+            message: 'All recipients were permanently rejected',
+            errorType: 'protocol',
+            retryable: false,
+            smtpCode: 550,
+            phase: 'rcpt_to',
+            transactionLog: [],
+            recipients: disposition.permanentFailures,
+          });
+        }
+      }
+
+      const deliveryTransitioned = await this.queue.markDelivered(item.id);
+      if (!deliveryTransitioned) return;
       
       // Update statistics
       this.stats.totalSuccessful++;
@@ -343,14 +572,17 @@ export class MultiModeDeliverySystem extends EventEmitter {
       this.deliveryTimes.push(deliveryTime);
       this.updateDeliveryTimeStats();
       
-      // Call delivery success hook
-      await this.options.onDeliverySuccess(item, result);
-      
-      // Emit delivery success event
-      this.emit('deliverySuccess', item, result);
+      await callObserverSafely(
+        'delivery success hook',
+        this.options.onDeliverySuccess,
+        item,
+        result,
+      );
+
+      await emitSafely(this, 'deliverySuccess', item, result);
       logger.log('info', `Item ${item.id} delivered successfully in ${deliveryTime}ms`);
       
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('delivery security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.INFO,
         type: SecurityEventType.EMAIL_DELIVERY,
         message: 'Email delivery successful',
@@ -361,75 +593,85 @@ export class MultiModeDeliverySystem extends EventEmitter {
           deliveryTime
         },
         success: true
-      });
-    } catch (error: any) {
+      }));
+    } catch (error: unknown) {
       // Calculate delivery attempt time even for failures
       const deliveryTime = Date.now() - startTime;
+      const deliveryError = SmtpDeliveryError.from(error);
       
-      // Mark as failed
-      await this.queue.markFailed(item.id, error.message);
-      
-      // Update statistics
-      this.stats.totalFailed++;
-      this.stats.byMode[item.processingMode].failed++;
-      
-      // Call delivery failed hook
-      await this.options.onDeliveryFailed(item, error.message);
+      if (
+        deliveryError.phase === 'rcpt_to'
+        && typeof deliveryError.smtpCode === 'number'
+        && deliveryError.smtpCode >= 500
+      ) {
+        const permanentRecipients = deliveryError.recipients.length > 0
+          ? deliveryError.recipients
+          : item.processingResult.getAllRecipients();
+        await this.queue.markRecipientsTerminal(
+          item.id,
+          permanentRecipients.map((recipient) => ({
+            recipient,
+            smtpCode: deliveryError.smtpCode!,
+            smtpResponse: deliveryError.message,
+          })),
+        );
+      }
+
+      const transition = await this.queue.markFailedWithTransition(item.id, deliveryError.message, {
+        retryable: deliveryError.retryable,
+      });
+      if (this.running) void this.drainBounceOutbox();
+      if (!transition.updated) return;
       
-      // Process as bounce if enabled and we have a bounce handler
-      if (this.options.processBounces && this.options.bounceHandler) {
-        try {
-          const email = item.processingResult as Email;
-          
-          // Extract recipient and error message
-          // For multiple recipients, we'd need more sophisticated parsing
-          const recipient = email.to.length > 0 ? email.to[0] : '';
-          
-          if (recipient) {
-            logger.log('info', `Processing delivery failure as bounce for recipient ${recipient}`);
-            
-            // Process SMTP failure through bounce handler
-            await this.options.bounceHandler.processSmtpFailure(
-              recipient,
-              error.message,
-              {
-                sender: email.from,
-                originalEmailId: item.id,
-                headers: email.headers
-              }
-            );
-            
-            logger.log('info', `Bounce record created for failed delivery to ${recipient}`);
-          }
-        } catch (bounceError) {
-          logger.log('error', `Failed to process bounce: ${bounceError.message}`);
-        }
+      // Intermediate retry attempts are deferrals, not failed deliveries.
+      if (transition.terminal) {
+        this.stats.totalFailed++;
+        this.stats.byMode[item.processingMode].failed++;
+        await callObserverSafely(
+          'delivery failure hook',
+          this.options.onDeliveryFailed,
+          item,
+          deliveryError.message,
+        );
       }
       
       // Emit delivery failed event
-      this.emit('deliveryFailed', item, error);
-      logger.log('error', `Item ${item.id} delivery failed: ${error.message}`);
+      if (transition.terminal) {
+        await emitSafely(this, 'deliveryFailed', item, deliveryError);
+        await emitSafely(this, 'deliveryTerminalFailure', item, deliveryError, transition);
+      } else {
+        await emitSafely(this, 'deliveryDeferred', item, deliveryError, transition);
+      }
+      logger.log(
+        transition.terminal ? 'error' : 'warn',
+        `Item ${item.id} delivery ${transition.terminal ? 'failed' : 'deferred'}: ${deliveryError.message}`,
+      );
       
-      SecurityLogger.getInstance().logEvent({
-        level: SecurityLogLevel.ERROR,
+      await callObserverSafely('delivery security log', () => SecurityLogger.getInstance().logEvent({
+        level: transition.terminal ? SecurityLogLevel.ERROR : SecurityLogLevel.WARN,
         type: SecurityEventType.EMAIL_DELIVERY,
-        message: 'Email delivery failed',
+        message: transition.terminal ? 'Email delivery failed' : 'Email delivery deferred',
         details: {
           itemId: item.id,
           mode: item.processingMode,
           routeName: item.route?.name || 'unknown',
-          error: error.message,
+          error: deliveryError.message,
+          errorType: deliveryError.errorType,
+          retryable: deliveryError.retryable,
+          phase: deliveryError.phase,
+          smtpCode: deliveryError.smtpCode,
+          queueStatus: transition.status,
           deliveryTime
         },
         success: false
-      });
+      }));
     } finally {
       // Remove from active deliveries
       this.activeDeliveries.delete(item.id);
       this.stats.activeDeliveries = this.activeDeliveries.size;
       
       // Update statistics
-      this.emit('statsUpdated', this.stats);
+      await emitSafely(this, 'statsUpdated', this.stats);
     }
   }
   
@@ -451,8 +693,18 @@ export class MultiModeDeliverySystem extends EventEmitter {
       throw new Error('No target server configured for forward mode');
     }
 
+    const deliveredRecipients = new Set(
+      (item.deliveredRecipients || []).map((recipient) => recipient.toLowerCase()),
+    );
+    const recipients = email
+      .getAllRecipients()
+      .filter((recipient) => !deliveredRecipients.has(recipient.toLowerCase()));
+    if (recipients.length === 0) {
+      return { targetServer, targetPort, recipients: 0, rejectedRecipients: [] };
+    }
     logger.log('info', `Forwarding email to ${targetServer}:${targetPort}`);
 
+    const startedAt = new Date();
     try {
       if (!this.emailServer) {
         throw new Error('No email server available for forward delivery');
@@ -460,7 +712,7 @@ export class MultiModeDeliverySystem extends EventEmitter {
 
       // Build DKIM options from route config
       const dkimDomain = item.route?.action.options?.mtaOptions?.dkimSign
-        ? (item.route.action.options.mtaOptions.dkimOptions?.domainName || email.from.split('@')[1])
+        ? (item.route.action.options.mtaOptions.dkimOptions?.domainName || email.getFromDomain() || undefined)
         : undefined;
       const dkimSelector = item.route?.action.options?.mtaOptions?.dkimOptions?.keySelector || 'default';
 
@@ -468,10 +720,44 @@ export class MultiModeDeliverySystem extends EventEmitter {
       const auth = route?.action.forward?.auth as { user: string; pass: string } | undefined;
 
       // Send via Rust SMTP client
-      const result = await this.emailServer.sendOutboundEmail(targetServer, targetPort, email, {
+      const result = await this.emailServer.sendOutboundEmail(
+        targetServer,
+        targetPort,
+        this.createEmailForRecipients(email, recipients),
+        {
         auth,
         dkimDomain,
         dkimSelector,
+        },
+      );
+
+      await this.queue.markRecipientsDelivered(item.id, result.accepted);
+      if (result.rejected.length > 0) {
+        const partialError = new SmtpDeliveryError({
+          message: `SMTP target rejected ${result.rejected.length} recipient(s) without a retained response code`,
+          errorType: 'partial_recipient_rejection',
+          retryable: true,
+          phase: 'rcpt_to',
+          transactionLog: result.transactionLog,
+          recipients: result.rejected,
+        });
+        await this.persistSmtpAttempt({
+          item,
+          targetHost: targetServer,
+          targetPort,
+          recipients,
+          startedAt,
+          error: partialError,
+        });
+        throw partialError;
+      }
+      await this.persistSmtpAttempt({
+        item,
+        targetHost: targetServer,
+        targetPort,
+        recipients,
+        startedAt,
+        result,
       });
 
       logger.log('info', `Email forwarded successfully to ${targetServer}:${targetPort}`);
@@ -483,9 +769,20 @@ export class MultiModeDeliverySystem extends EventEmitter {
         messageId: result.messageId,
         rejectedRecipients: result.rejected,
       };
-    } catch (error: any) {
-      logger.log('error', `Failed to forward email: ${error.message}`);
-      throw error;
+    } catch (error: unknown) {
+      const smtpError = this.contextualizeSmtpError(error, recipients);
+      if (!(error instanceof SmtpDeliveryError && error.errorType === 'partial_recipient_rejection')) {
+        await this.persistSmtpAttempt({
+          item,
+          targetHost: targetServer,
+          targetPort,
+          recipients,
+          startedAt,
+          error: smtpError,
+        });
+      }
+      logger.log('error', `Failed to forward email: ${smtpError.message}`);
+      throw smtpError;
     }
   }
   
@@ -519,6 +816,39 @@ export class MultiModeDeliverySystem extends EventEmitter {
     return groups;
   }
 
+  private aggregateSmtpFailures(
+    failures: SmtpDeliveryError[],
+    recipients: string[],
+    recipientDomain?: string,
+  ): SmtpDeliveryError {
+    const normalized = failures.length > 0
+      ? failures
+      : [SmtpDeliveryError.from(new Error('SMTP delivery failed without error details'))];
+    const retryable = normalized.some((failure) => failure.retryable);
+    const allPermanentRecipientRejections = normalized.every((failure) => (
+      !failure.retryable
+      && failure.errorType === 'protocol'
+      && failure.phase === 'rcpt_to'
+      && typeof failure.smtpCode === 'number'
+      && failure.smtpCode >= 500
+    ));
+    const selected = normalized.find((failure) => failure.retryable)
+      || normalized[normalized.length - 1];
+    const smtpCode = allPermanentRecipientRejections
+      ? Math.max(...normalized.map((failure) => failure.smtpCode || 500))
+      : selected.smtpCode;
+    return new SmtpDeliveryError({
+      message: normalized.map((failure) => failure.message).join('; '),
+      errorType: allPermanentRecipientRejections ? 'protocol' : 'smtp_aggregate',
+      retryable,
+      ...(smtpCode !== undefined ? { smtpCode } : {}),
+      phase: allPermanentRecipientRejections ? 'rcpt_to' : selected.phase,
+      transactionLog: [],
+      recipients,
+      ...(recipientDomain ? { recipientDomain } : {}),
+    }, selected);
+  }
+
   /**
    * Default handler for MTA mode delivery
    * @param item Queue item
@@ -533,8 +863,11 @@ export class MultiModeDeliverySystem extends EventEmitter {
     }
 
     // Build DKIM options from route config
-    const dkimDomain = item.route?.action.options?.mtaOptions?.dkimSign
-      ? (item.route.action.options.mtaOptions.dkimOptions?.domainName || email.from.split('@')[1])
+    const effectiveDkimSigning = Boolean(
+      item.route?.action.options?.mtaOptions?.dkimSign || item.route?.action.process?.dkim,
+    );
+    const dkimDomain = effectiveDkimSigning
+      ? (item.route?.action.options?.mtaOptions?.dkimOptions?.domainName || email.getFromDomain() || undefined)
       : undefined;
     const dkimSelector = item.route?.action.options?.mtaOptions?.dkimOptions?.keySelector || 'default';
 
@@ -543,8 +876,30 @@ export class MultiModeDeliverySystem extends EventEmitter {
       throw new Error('No recipients specified for MTA delivery');
     }
 
-    const domainGroups = this.groupRecipientsByDomain(allRecipients);
+    const deliveredRecipients = new Set(
+      (item.deliveredRecipients || []).map((recipient) => recipient.toLowerCase()),
+    );
+    const terminalRecipients = new Set(
+      (item.terminalRecipients || []).map((recipient) => recipient.toLowerCase()),
+    );
+    const pendingRecipients = allRecipients.filter(
+      (recipient) => (
+        !deliveredRecipients.has(recipient.toLowerCase())
+        && !terminalRecipients.has(recipient.toLowerCase())
+      ),
+    );
+    if (pendingRecipients.length === 0) {
+      return {
+        recipientDispositionManaged: true,
+        recipients: allRecipients.length,
+        domainResults: [],
+      };
+    }
+
+    const domainGroups = this.groupRecipientsByDomain(pendingRecipients);
     const results: Array<{ domain: string; success: boolean; error?: string; accepted?: string[]; rejected?: string[] }> = [];
+    const unresolvedFailures: SmtpDeliveryError[] = [];
+    const unresolvedRecipients: string[] = [];
 
     for (const [domain, recipients] of domainGroups) {
       const allMxHosts = await this.resolveMxForDomain(domain);
@@ -555,66 +910,172 @@ export class MultiModeDeliverySystem extends EventEmitter {
       const mxHosts = allMxHosts.filter(mx => !this.emailServer!.isSelfHostname(mx.exchange));
       if (mxHosts.length === 0) {
         const selfMx = allMxHosts.map(mx => mx.exchange).join(', ');
+        const loopError = new SmtpDeliveryError({
+          message: `MX for ${domain} (${selfMx || 'none'}) points back at this server — refusing self-delivery to avoid a mail loop`,
+          errorType: 'config',
+          retryable: false,
+          phase: 'connect',
+          transactionLog: [],
+          recipients,
+          recipientDomain: domain,
+        });
+        unresolvedFailures.push(loopError);
+        unresolvedRecipients.push(...recipients);
         results.push({
           domain,
           success: false,
-          error: `MX for ${domain} (${selfMx || 'none'}) points back at this server — refusing self-delivery to avoid a mail loop`,
+          error: loopError.message,
         });
         logger.log('error', `MTA: refusing self-delivery for ${domain} — MX (${selfMx}) is this server's own hostname (mail loop)`);
         continue;
       }
 
-      let delivered = false;
-      let lastError: string | undefined;
+      let recipientsForMx = [...recipients];
+      const domainFailures: SmtpDeliveryError[] = [];
+      const acceptedForDomain: string[] = [];
 
       for (const mx of mxHosts) {
+        if (recipientsForMx.length === 0) break;
+        const startedAt = new Date();
         try {
           logger.log('info', `MTA: trying MX ${mx.exchange}:25 for domain ${domain} (priority ${mx.priority})`);
 
           // Create a temporary Email scoped to this domain's recipients
-          const domainEmail = new Email({
-            from: email.from,
-            to: recipients.filter(r => email.to.includes(r)),
-            cc: recipients.filter(r => (email.cc || []).includes(r)),
-            bcc: recipients.filter(r => (email.bcc || []).includes(r)),
-            subject: email.subject,
-            text: email.text,
-            html: email.html,
-          });
+          const domainEmail = this.createEmailForRecipients(email, recipientsForMx);
 
           const result = await this.emailServer.sendOutboundEmail(mx.exchange, 25, domainEmail, {
             dkimDomain,
             dkimSelector,
           });
 
-          results.push({
-            domain,
-            success: true,
-            accepted: result.accepted,
-            rejected: result.rejected,
+          const disposition = this.splitRecipientResults(
+            result.recipientResults,
+            result.rejected,
+          );
+          const accepted = disposition.accepted.length > 0
+            ? disposition.accepted
+            : result.accepted;
+          await this.queue.markRecipientsDelivered(item.id, accepted);
+          acceptedForDomain.push(...accepted);
+          await this.checkpointPermanentRecipientFailures(
+            item,
+            disposition.permanent,
+          );
+          await this.persistSmtpAttempt({
+            item,
+            targetHost: mx.exchange,
+            targetPort: 25,
+            recipientDomain: domain,
+            recipients: recipientsForMx,
+            startedAt,
+            result,
           });
-          delivered = true;
-          logger.log('info', `MTA: delivered to ${domain} via ${mx.exchange}`);
-          break;
-        } catch (err: any) {
-          lastError = err.message;
-          logger.log('warn', `MTA: MX ${mx.exchange} failed for ${domain}: ${err.message}`);
+          recipientsForMx = disposition.transient;
+          if (recipientsForMx.length === 0) {
+            logger.log('info', `MTA: completed recipient dispositions for ${domain} via ${mx.exchange}`);
+            break;
+          }
+          domainFailures.push(new SmtpDeliveryError({
+            message: `MX ${mx.exchange} temporarily rejected ${recipientsForMx.length} recipient(s)`,
+            errorType: 'protocol',
+            retryable: true,
+            smtpCode: result.recipientResults
+              ? Math.min(
+                  ...result.recipientResults
+                    .filter((entry) => recipientsForMx.includes(entry.recipient))
+                    .map((entry) => entry.responseCode),
+                )
+              : 451,
+            phase: 'rcpt_to',
+            transactionLog: result.transactionLog,
+            recipients: recipientsForMx,
+            recipientDomain: domain,
+            recipientResults: result.recipientResults?.filter(
+              (entry) => recipientsForMx.includes(entry.recipient),
+            ),
+          }));
+        } catch (error: unknown) {
+          const smtpError = this.contextualizeSmtpError(error, recipientsForMx, domain);
+          if (!(error instanceof SmtpDeliveryError && error.errorType === 'partial_recipient_rejection')) {
+            await this.persistSmtpAttempt({
+              item,
+              targetHost: mx.exchange,
+              targetPort: 25,
+              recipientDomain: domain,
+              recipients: recipientsForMx,
+              startedAt,
+              error: smtpError,
+            });
+          }
+          const disposition = smtpError.phase === 'rcpt_to'
+            ? (
+                smtpError.recipientResults.length > 0
+                  ? this.splitRecipientResults(smtpError.recipientResults, smtpError.recipients)
+                  : (
+                      typeof smtpError.smtpCode === 'number' && smtpError.smtpCode >= 500
+                        ? {
+                            accepted: [],
+                            permanent: recipientsForMx.map((recipient) => ({
+                              recipient,
+                              accepted: false,
+                              responseCode: smtpError.smtpCode!,
+                            })),
+                            transient: [],
+                          }
+                        : { accepted: [], permanent: [], transient: [...recipientsForMx] }
+                    )
+              )
+            : { accepted: [], permanent: [], transient: [] };
+          if (disposition.accepted.length > 0) {
+            await this.queue.markRecipientsDelivered(item.id, disposition.accepted);
+            acceptedForDomain.push(...disposition.accepted);
+          }
+          await this.checkpointPermanentRecipientFailures(
+            item,
+            disposition.permanent,
+          );
+          if (smtpError.phase === 'rcpt_to') {
+            recipientsForMx = disposition.transient;
+          }
+          if (recipientsForMx.length > 0) {
+            domainFailures.push(smtpError);
+          }
+          logger.log('warn', `MTA: MX ${mx.exchange} failed for ${domain}: ${smtpError.message}`);
         }
       }
 
-      if (!delivered) {
-        results.push({ domain, success: false, error: lastError });
+      if (recipientsForMx.length > 0) {
+        const domainError = this.aggregateSmtpFailures(
+          domainFailures,
+          recipientsForMx,
+          domain,
+        );
+        unresolvedFailures.push(domainError);
+        unresolvedRecipients.push(...recipientsForMx);
+        results.push({
+          domain,
+          success: false,
+          error: domainError.message,
+          accepted: acceptedForDomain,
+          rejected: recipientsForMx,
+        });
         logger.log('error', `MTA: all MX hosts failed for ${domain}`);
+      } else {
+        results.push({
+          domain,
+          success: true,
+          accepted: acceptedForDomain,
+          rejected: [],
+        });
       }
     }
 
-    const allFailed = results.every(r => !r.success);
-    if (allFailed) {
-      const summary = results.map(r => `${r.domain}: ${r.error}`).join('; ');
-      throw new Error(`MTA delivery failed for all domains: ${summary}`);
+    if (unresolvedRecipients.length > 0) {
+      throw this.aggregateSmtpFailures(unresolvedFailures, unresolvedRecipients);
     }
 
     return {
+      recipientDispositionManaged: true,
       recipients: allRecipients.length,
       domainResults: results,
     };
@@ -684,11 +1145,6 @@ export class MultiModeDeliverySystem extends EventEmitter {
         }
       }
       
-      // Apply DKIM signing if configured (after all transformations)
-      if (item.route?.action.options?.mtaOptions?.dkimSign || item.route?.action.process?.dkim) {
-        await this.applyDkimSigning(email, item.route.action.options?.mtaOptions || {});
-      }
-      
       logger.log('info', `Email successfully processed in store-and-forward mode, delivering via MTA`);
 
       // After scanning + transformations, deliver via MTA
@@ -706,49 +1162,6 @@ export class MultiModeDeliverySystem extends EventEmitter {
     return filename.substring(filename.lastIndexOf('.')).toLowerCase();
   }
   
-  /**
-   * Apply DKIM signing to an email
-   */
-  private async applyDkimSigning(email: Email, mtaOptions: any): Promise<void> {
-    if (!this.emailServer) {
-      logger.log('warn', 'Cannot apply DKIM signing without email server reference');
-      return;
-    }
-    
-    const domainName = mtaOptions.dkimOptions?.domainName || email.from.split('@')[1];
-    const keySelector = mtaOptions.dkimOptions?.keySelector || 'default';
-    
-    try {
-      // Ensure DKIM keys exist for the exact selector advertised in the signature.
-      await this.emailServer.dkimCreator.handleDKIMKeysForSelector(domainName, keySelector);
-
-      // Load the private key for that same selector.
-      const dkimPrivateKey = (
-        await this.emailServer.dkimCreator.readDKIMKeysForSelector(domainName, keySelector)
-      ).privateKey;
-
-      // Convert Email to raw format for signing
-      const rawEmail = email.toRFC822String();
-
-      // Sign via Rust bridge
-      const bridge = RustSecurityBridge.getInstance();
-      const signResult = await bridge.signDkim({
-        rawMessage: rawEmail,
-        domain: domainName,
-        selector: keySelector,
-        privateKey: dkimPrivateKey,
-      });
-
-      if (signResult.header) {
-        email.addHeader('DKIM-Signature', signResult.header);
-        logger.log('info', `Successfully added DKIM signature for ${domainName}`);
-      }
-    } catch (error) {
-      logger.log('error', `Failed to apply DKIM signature: ${error.message}`);
-      // Don't throw - allow email to be sent without DKIM if signing fails
-    }
-  }
-  
   /**
    * Update delivery time statistics
    */