@push.rocks/smartmta 8.2.1 → 9.0.0

package/dist_ts/mail/routing/interfaces.d.ts

@@ -41,9 +41,21 @@ export interface IEmailMatch {
  * Action to take when route matches
  */
 export interface IEmailAction {
-    /** Type of action to perform */
+    /**
+     * Type of action to perform.
+     * - `forward`: relay to a configured SMTP host.
+     * - `process`: queue for scanning and outbound MX delivery.
+     * - `deliver`: terminal local delivery through the durable
+     *   `hooks.onAcceptEnvelope` acceptance path. Never relays.
+     * - `store`: terminal local delivery like `deliver`, with explicit
+     *   retention configuration.
+     * - `reject`: refuse with a configurable SMTP error.
+     */
     type: 'forward' | 'deliver' | 'reject' | 'process' | 'store';
-    /** Explicitly permits this route to relay to non-local recipients. */
+    /**
+     * Explicitly permits this route to relay to non-local recipients.
+     * Ignored for `deliver` actions, which are local-only and never relay.
+     */
     allowRelay?: boolean;
     /** Forward action configuration */
     forward?: {
@@ -116,7 +128,7 @@ export interface IEmailAction {
             [key: string]: any;
         }>;
     };
-    /** Delivery options (applies to forward/process/deliver) */
+    /** Delivery options (applies to the queue-backed forward/process actions) */
     delivery?: {
         /** Rate limit (messages per minute) */
         rateLimit?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmta",
-  "version": "8.2.1",
+  "version": "9.0.0",
   "description": "A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.",
   "keywords": [
     "mta",
@@ -31,9 +31,9 @@
     ".": "./dist_ts/index.js"
   },
   "devDependencies": {
-    "@git.zone/cli": "^2.23.0",
+    "@git.zone/cli": "^3.0.0",
     "@git.zone/tsbuild": "4.4.2",
-    "@git.zone/tsrust": "^1.6.0",
+    "@git.zone/tsrust": "^1.7.0",
     "@git.zone/tstest": "^3.6.6",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^26.1.1",

package/readme.md

@@ -29,7 +29,7 @@ After installation, run `pnpm build` to compile the Rust binary (`mailer-bin`).
 | **DKIM** | Key generation, signing, and verification — per domain, with automatic rotation |
 | **SPF** | Full SPF record validation via Rust |
 | **DMARC** | Policy enforcement and verification |
-| **Email Router** | Pattern-based routing with priority, forward/deliver/reject/process actions |
+| **Email Router** | Pattern-based routing with priority, forward/process/reject actions plus terminal local `deliver`/`store` actions |
 | **Bounce Manager** | Automatic bounce detection via Rust, classification (hard/soft), and suppression tracking |
 | **Content Scanner** | Spam, phishing, malware, XSS, and suspicious link detection — powered by Rust |
 | **IP Reputation** | DNSBL checks, proxy/TOR/VPN detection, risk scoring via Rust |
@@ -171,7 +171,8 @@ const emailServer = new UnifiedEmailServer(dcRouterRef, {
     securePort: 465,
     recipientValidationTimeoutMs: 5000,
 
-    // Timeout for hooks.onMessageData before returning a temporary SMTP failure.
+    // Timeout for hooks.onMessageData and hooks.onAcceptEnvelope before
+    // returning a temporary SMTP failure.
     messageAcceptanceTimeoutMs: 30000,
 
     // Set required to true only on backend listeners reached through trusted proxies.
@@ -197,10 +198,19 @@ const emailServer = new UnifiedEmailServer(dcRouterRef, {
       return { accepted: false, smtpCode: 550, smtpMessage: 'Relay not permitted' };
     },
     async onMessageData(context) {
+      // Runs for envelopes WITHOUT a resolved store/deliver action.
       // Return accepted only after the consumer has taken responsibility for the message.
       // await durableStore.save(context.email, context.rawMessage, { signal: context.abortSignal });
       return { accepted: true, continueProcessing: false };
     },
+    async onAcceptEnvelope(context) {
+      // Required terminal durable owner for envelopes with a resolved
+      // `store` or `deliver` action. Durably persist the EXACT raw bytes and
+      // the per-recipient plan before resolving — the SMTP 250 is only sent
+      // after this hook resolves.
+      // const plan = emailServer.createAcceptedEnvelopeDispatchPlan(context, idempotencyKeys);
+      // await durableStore.saveEnvelope(context.rawMessage, plan, { signal: context.abortSignal });
+    },
   },
 
   // Authentication settings for the SMTP server
@@ -241,7 +251,7 @@ await emailServer.start();
 
 > 🔒 **Note:** `start()` will throw if the Rust binary is not compiled. Run `pnpm build` first.
 >
-> SmartMTA 8 requires Node.js 22 or newer.
+> SmartMTA requires Node.js 22 or newer.
 >
 > `hostname` is the public SMTP identity for greetings and outbound delivery by default. It is not a bind address.
 >
@@ -268,11 +278,13 @@ Bounce delivery is at-least-once. `BounceManager` uses the operation ID as a dur
 
 SmartMTA validates each `RCPT TO` before the client can enter `DATA` by default. The default policy evaluates routes and accepts configured local domains. External recipients are rejected unless the matched route action explicitly sets `allowRelay: true`. Set `smtp.recipientValidation: false` only on fully trusted private listeners where another layer performs recipient and relay policy.
 
-Use `allowRelay` only for intentional relay routes, for example authenticated submission or tightly scoped internal networks. Broad `process` or `deliver` routes do not grant relay permission by themselves.
+Use `allowRelay` only for intentional relay routes, for example authenticated submission or tightly scoped internal networks. Broad `process` routes do not grant relay permission by themselves, and `deliver` routes can never relay — `allowRelay` is ignored for them.
+
+`hooks.onRcptTo`, `hooks.onMessageData`, and `hooks.onAcceptEnvelope` are awaited asynchronously. If a hook throws or times out, SmartMTA returns a temporary SMTP failure. The hook context includes `abortSignal`; long-running consumers should observe it and stop work promptly. A custom `onRcptTo` hook may accept local recipients using application-specific lookup, but external relay is still blocked unless a matched route explicitly sets `allowRelay: true`.
 
-`hooks.onRcptTo` and `hooks.onMessageData` are awaited asynchronously. If a hook throws or times out, SmartMTA returns a temporary SMTP failure. The hook context includes `abortSignal`; long-running consumers should observe it and stop work promptly. A custom `onRcptTo` hook may accept local recipients using application-specific lookup, but external relay is still blocked unless a matched route explicitly sets `allowRelay: true`.
+`hooks.onMessageData` runs after `DATA` and before the final SMTP response — but only for envelopes with **no** resolved `store` or `deliver` action; terminal local deliveries go through `hooks.onAcceptEnvelope` instead and never invoke `onMessageData`. Return `{ accepted: true }` only after your application has accepted responsibility for the message, such as after durable persistence. Set `continueProcessing: false` when the consumer owns all downstream processing.
 
-`hooks.onMessageData` runs after `DATA` and before the final SMTP response. Return `{ accepted: true }` only after your application has accepted responsibility for the message, such as after durable persistence. Set `continueProcessing: false` when the consumer owns all downstream processing.
+`hooks.onAcceptEnvelope` is the terminal durable owner for any envelope containing a resolved `store` or `deliver` action. It receives the exact raw RFC822 bytes (`rawMessage`), the complete per-recipient route resolution (`resolvedRecipientRoutes`), and the Rust security verdicts (`securityResults`). It must durably persist the message before resolving — the SMTP `250` is only sent after the hook resolves. Throwing an `AcceptEnvelopeRejectionError` with a `5xx` code rejects the envelope permanently with that status; any other error or a `smtp.messageAcceptanceTimeoutMs` timeout refuses the envelope with a temporary `451`. Use `createAcceptedEnvelopeDispatchPlan()` inside the hook to snapshot the resolved plan for later replay-safe `dispatchAcceptedEnvelope()` calls. Both `AcceptEnvelopeRejectionError` and `IAcceptEnvelopeContext` are exported.
 
 Use `smtp.securePort` when the implicit TLS listener uses a remapped backend port instead of public `465`; the configured secure port must also be present in `ports`, otherwise `start()` throws.
 
@@ -344,6 +356,8 @@ public async sendEmail(
 
 **Self-MX loop guard:** MTA delivery refuses any MX host that equals the server's own hostname (`hostname` or `outbound.hostname`). A domain whose MX record points back at this server would otherwise re-enter the inbound pipeline on every delivery attempt — an infinite mail loop. Such deliveries fail with `MX for <domain> points back at this server — refusing self-delivery to avoid a mail loop`. The comparison is hostname-based; if a target only reveals the loop at the IP level (e.g. an A-record fallback), embedders should add an IP-level guard in their `connectionProxyProvider`.
 
+Routes with action `deliver` never enter MTA mode: they are terminal local deliveries through the durable acceptance path (see Route Action Types below), so the self-MX guard is structurally unreachable for them. Pre-9.x persisted queue items that still carry a `deliver` action fail loudly at delivery time with error type `deliver_action_relay_unsupported` (failure class `localTopology`) instead of being relayed or bounced as a misleading self-MX loop.
+
 ### 📬 Direct SMTP Delivery (Low-Level)
 
 For cases where you know the exact target SMTP server (e.g. relaying to a specific host), use the lower-level `sendOutboundEmail()`:
@@ -427,7 +441,7 @@ When `UnifiedEmailServer.start()` is called:
 - A requested missing or invalid key fails closed before SMTP delivery. SmartMTA never falls back to unsigned delivery.
 - Signing is applied exactly once, by the Rust SMTP client at final outbound transmission.
 
-Embedders can check `smartMtaCapabilities.selectorCorrectDkimSigning`, `callerManagedDkimKeys`, `structuredSmtpTransactions`, and `typedDeliveryFailures` as compatibility probes.
+Embedders can check `smartMtaCapabilities.selectorCorrectDkimSigning`, `callerManagedDkimKeys`, `structuredSmtpTransactions`, `typedDeliveryFailures`, and `terminalLocalDeliverActions` (deliver routes are terminal local deliveries through the durable acceptance path) as compatibility probes.
 
 ### 🛡️ Email Authentication (SPF, DKIM, DMARC)
 
@@ -460,6 +474,8 @@ const router = new EmailRouter([
       authenticated: true,
     },
     action: {
+      // Terminal local delivery. In UnifiedEmailServer this requires a
+      // configured hooks.onAcceptEnvelope durable local-delivery owner.
       type: 'deliver',
     },
   },
@@ -505,11 +521,23 @@ const matchedRoute = await router.evaluateRoutes(emailContext);
 | Action | Description |
 |---|---|
 | `forward` | Forward the email to another SMTP server via the Rust SMTP client |
-| `deliver` | Queue for local MTA delivery |
-| `process` | Queue for processing (with optional content scanning and DKIM signing) |
+| `deliver` | **Terminal local delivery.** The envelope is durably accepted through `hooks.onAcceptEnvelope` before the SMTP 250; nothing is enqueued for outbound MX relay. |
+| `store` | Terminal local delivery like `deliver`, with explicit retention configuration (`store.retentionDays`) |
+| `process` | Queue for processing (with optional content scanning and DKIM signing), then deliver via automatic MX resolution |
 | `reject` | Reject with a configurable SMTP error code and message |
 
-Every action can include `allowRelay?: boolean`. It defaults to `false`. Non-local recipients are accepted only when the matched action explicitly sets `allowRelay: true`; configured local domains remain eligible for inbound delivery without relay permission.
+##### Local delivery: `deliver` and `store`
+
+`deliver` and `store` are the two terminal local-delivery actions. An envelope that resolves to either goes through the durable acceptance path: SmartMTA calls `hooks.onAcceptEnvelope` with the exact raw message and the complete per-recipient plan, and only sends the SMTP `250` after the hook resolves — the consumer's durably persisted copy IS the delivery. In `dispatchAcceptedEnvelope`, both report `status: 'stored'` with no `queueId`; the `actionType` field distinguishes them.
+
+- A `deliver` route **requires** a configured `hooks.onAcceptEnvelope`. Without it the configuration is unservable and is rejected loudly whenever routes are supplied or loaded: the constructor, `updateEmailRoutes`, `updateOptions` calls that include `routes`, and persisted-route hydration all throw. If hook state is nevertheless broken at runtime (for example an `updateOptions` call that replaces `hooks` without passing `routes`), deliver recipients are refused with a temporary `451 Local delivery temporarily unavailable` at `RCPT TO`/`DATA`. Mail is never accepted and then destroyed.
+- `deliver` never relays. Non-local recipients matched by a deliver route are refused with `550` at `RCPT TO`, and `allowRelay` is ignored for deliver actions.
+- `deliver` envelopes skip `hooks.onMessageData`, bounce-notification detection, and the inbound `processEmailByMode` pipeline — exactly like `store` envelopes. Rust-computed security verdicts are still delivered in the acceptance context.
+- `deliver` carries no retention metadata; the consumer owns retention for delivered messages. Use `store` with `store.retentionDays` when retention must be explicit.
+
+> ⚠️ **Changed in v9:** before v9, `deliver` silently meant "relay via MX discovery". On a domain whose MX points back at this server, that accepted mail with `250` and then terminally bounced it on the self-MX loop guard — destroying mail. `deliver` now delivers locally, and configurations that cannot do so fail at config/accept time.
+
+Every action can include `allowRelay?: boolean`. It defaults to `false`. Non-local recipients are accepted only when the matched action explicitly sets `allowRelay: true`; configured local domains remain eligible for inbound delivery without relay permission. `allowRelay` has no effect on `deliver` actions.
 
 #### Match Criteria
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmta',
-  version: '8.2.1',
+  version: '9.0.0',
   description: 'A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.'
 }

package/ts/index.ts

@@ -14,4 +14,5 @@ export const smartMtaCapabilities = Object.freeze({
   topologyAwareSelfMx: true,
   durableDeliveryFailureOutbox: true,
   exactAcceptedEnvelopeDispatch: true,
+  terminalLocalDeliverActions: true,
 } as const);

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

@@ -675,7 +675,10 @@ export class MultiModeDeliverySystem extends EventEmitter {
       const transition = await this.queue.markFailedWithTransition(item.id, deliveryError.message, {
         retryable: deliveryError.retryable,
         terminalFailure: {
-          failureClass: deliveryError.errorType.startsWith('self_mx_')
+          failureClass: (
+            deliveryError.errorType.startsWith('self_mx_')
+            || deliveryError.errorType === 'deliver_action_relay_unsupported'
+          )
             ? 'localTopology'
             : 'transport',
           ...(deliveryError.smtpCode !== undefined ? { smtpCode: deliveryError.smtpCode } : {}),
@@ -926,6 +929,22 @@ export class MultiModeDeliverySystem extends EventEmitter {
 
     const email = item.processingResult as Email;
 
+    // Structural invariant: `deliver` actions are terminal local deliveries
+    // and must never reach outbound MX relay (and thus never the self-MX
+    // guard below). Items carrying a deliver action can only be pre-9.x
+    // persisted queue state or a direct-enqueue misuse; both fail loudly
+    // here instead of relaying or bouncing as a misleading self-MX loop.
+    if (item.route?.action.type === 'deliver') {
+      throw new SmtpDeliveryError({
+        message: `Queue item ${item.id} carries a 'deliver' action; deliver is a terminal local delivery and cannot be relayed via MX`,
+        errorType: 'deliver_action_relay_unsupported',
+        retryable: false,
+        phase: 'connect',
+        transactionLog: [],
+        recipients: email.getAllRecipients(),
+      });
+    }
+
     if (!this.emailServer) {
       throw new Error('No email server available for MTA delivery');
     }

package/ts/mail/routing/classes.email.action.executor.ts

@@ -47,7 +47,10 @@ export interface IActionExecutionResult {
 }
 
 /**
- * Executes email routing actions (forward, process, deliver, reject)
+ * Executes queue-backed and rejecting email routing actions (forward,
+ * process, reject). Terminal local-delivery actions (`deliver`, `store`) are
+ * owned by the durable `hooks.onAcceptEnvelope` acceptance path and are
+ * refused here.
  */
 export class EmailActionExecutor {
   constructor(private deps: IActionExecutorDeps) {}
@@ -97,7 +100,9 @@ export class EmailActionExecutor {
       case 'process':
         return this.handleProcessAction(action, email, context, options);
       case 'deliver':
-        return this.handleDeliverAction(action, email, context, options);
+        throw new Error(
+          'Deliver actions are terminal local deliveries and require the durable hooks.onAcceptEnvelope acceptance path; they never enqueue outbound MX relay',
+        );
       case 'store':
         throw new Error(
           'Store actions require raw SMTP context and an awaited hooks.onAcceptEnvelope handler',
@@ -250,32 +255,6 @@ export class EmailActionExecutor {
     return { outcome: 'queued', queueId };
   }
 
-  private async handleDeliverAction(
-    _action: IEmailAction,
-    email: Email,
-    context: IEmailContext,
-    options: IActionExecutionOptions,
-  ): Promise<IActionExecutionResult> {
-    logger.log('info', `Delivering email locally`);
-
-    // Queue for local delivery
-    const queueId = await this.deps.deliveryQueue.enqueue(
-      email,
-      'mta',
-      context.session.matchedRoute!,
-      options.durableQueue
-        ? {
-            idempotencyKey: options.durableQueue.idempotencyKey,
-            idempotencyFingerprint: options.durableQueue.fingerprint,
-            requireDurable: true,
-          }
-        : {},
-    );
-
-    logger.log('info', 'Email queued for local delivery');
-    return { outcome: 'queued', queueId };
-  }
-
   private async handleRejectAction(action: IEmailAction, _email: Email, context: IEmailContext): Promise<void> {
     const code = action.reject?.code || 550;
     const message = action.reject?.message || 'Message rejected';

package/ts/mail/routing/classes.email.router.ts

@@ -14,8 +14,9 @@ export class EmailRouter extends EventEmitter {
   private patternCache: Map<string, boolean> = new Map();
   private storageManager?: IStorageManager;
   private persistChanges: boolean;
+  private validateAction?: (route: IEmailRoute) => void;
   private initializationPromise: Promise<void>;
-  
+
   /**
    * Create a new email router
    * @param routes Array of email routes
@@ -24,8 +25,15 @@ export class EmailRouter extends EventEmitter {
   constructor(routes: IEmailRoute[], options?: {
     storageManager?: IStorageManager;
     persistChanges?: boolean;
+    /**
+     * Additional owner-level action policy applied to every configured,
+     * updated, and hydrated route (e.g. an embedding server requiring a
+     * durable local-delivery owner for `deliver` actions).
+     */
+    validateAction?: (route: IEmailRoute) => void;
   }) {
     super();
+    this.validateAction = options?.validateAction;
     this.validateRoutes(routes);
     this.routes = this.sortRoutesByPriority(routes);
     this.storageManager = options?.storageManager;
@@ -49,6 +57,8 @@ export class EmailRouter extends EventEmitter {
       throw new Error('Invalid route: missing required fields');
     }
 
+    this.validateAction?.(route);
+
     if (route.action.type !== 'store') {
       return;
     }
@@ -69,6 +79,16 @@ export class EmailRouter extends EventEmitter {
       this.validateRoute(route);
     }
   }
+
+  /**
+   * Synchronously validate routes against structural rules and the owner's
+   * action policy without mutating router state. Callers that stage route
+   * updates in their own configuration should validate first so an invalid
+   * route set fails loudly before any state changes.
+   */
+  public assertRoutesValid(routes: IEmailRoute[]): void {
+    this.validateRoutes(routes);
+  }
   
   /**
    * Sort routes by priority (higher priority first)

package/ts/mail/routing/classes.unified.email.server.ts

@@ -147,8 +147,9 @@ export class AcceptEnvelopeRejectionError extends Error {
 }
 
 /**
- * Terminal durable acceptance context for an envelope containing at least one `store` route.
- * The consumer owns persistence and all recipient fan-out before this hook resolves.
+ * Terminal durable acceptance context for an envelope containing at least one
+ * `store` or `deliver` route. The consumer owns persistence and all recipient
+ * fan-out before this hook resolves.
  */
 export interface IAcceptEnvelopeContext {
   email: Email;
@@ -338,9 +339,14 @@ export interface IUnifiedEmailServerOptions {
   hooks?: {
     /** Async recipient policy hook that may further restrict an accepted built-in decision. */
     onRcptTo?: (context: IRcptToPolicyContext) => Promise<ISmtpDecision>;
-    /** Async message acceptance hook for envelopes with no resolved `store` action. */
+    /** Async message acceptance hook for envelopes with no resolved `store` or `deliver` action. */
     onMessageData?: (context: IMessageAcceptanceContext) => Promise<IMessageAcceptanceDecision>;
-    /** Required terminal durable owner for any envelope containing a resolved `store` action. */
+    /**
+     * Required terminal durable owner for any envelope containing a resolved
+     * `store` or `deliver` action. The hook must durably persist the exact
+     * raw message before resolving; its resolution is what authorizes the
+     * SMTP 250 for those envelopes.
+     */
     onAcceptEnvelope?: (context: IAcceptEnvelopeContext) => Promise<void>;
     /** Observer-safe callback for SMTP recipient rejections. */
     onRecipientRejected?: (event: IRecipientRejectedEvent) => Promise<void> | void;
@@ -488,10 +494,13 @@ export class UnifiedEmailServer extends EventEmitter {
     // Initialize domain registry
     this.domainRegistry = new DomainRegistry(options.domains, options.defaults);
 
-    // Initialize email router with routes and storage manager
+    // Initialize email router with routes and storage manager. The action
+    // policy applies to configured, updated, and storage-hydrated routes so
+    // an unservable route set fails loudly at configuration time.
     this.emailRouter = new EmailRouter(options.routes || [], {
       storageManager: dcRouter.storageManager,
-      persistChanges: options.persistRoutes ?? true
+      persistChanges: options.persistRoutes ?? true,
+      validateAction: (route) => this.assertRouteActionServable(route),
     });
 
     // Initialize rate limiter
@@ -1354,6 +1363,37 @@ export class UnifiedEmailServer extends EventEmitter {
         };
       }
 
+      if (route.action.type === 'deliver') {
+        if (!isLocalRecipient) {
+          // Deliver actions are terminal local deliveries and never relay;
+          // `allowRelay` is ignored for them.
+          return {
+            recipient: context.rcptTo,
+            localDomain: null,
+            route,
+            source: 'explicit-route',
+            decision: { accepted: false, smtpCode: 550, smtpMessage: 'Relay not permitted' },
+            rejectionReason: 'relay-denied',
+          };
+        }
+        if (!this.options.hooks?.onAcceptEnvelope) {
+          // Defense in depth: route validation rejects this configuration,
+          // so refuse loudly at accept time rather than accept-then-fail.
+          return {
+            recipient: context.rcptTo,
+            localDomain,
+            route,
+            source: 'explicit-route',
+            decision: {
+              accepted: false,
+              smtpCode: 451,
+              smtpMessage: 'Local delivery temporarily unavailable',
+            },
+            rejectionReason: 'policy-error',
+          };
+        }
+      }
+
       if (!isLocalRecipient && !route.action.allowRelay) {
         return {
           recipient: context.rcptTo,
@@ -2088,7 +2128,6 @@ export class UnifiedEmailServer extends EventEmitter {
     }
     const hasQueueAction = plan.some((entry) => (
       entry.action.type === 'forward'
-      || entry.action.type === 'deliver'
       || entry.action.type === 'process'
     ));
     if (hasQueueAction) {
@@ -2168,7 +2207,16 @@ export class UnifiedEmailServer extends EventEmitter {
 
       try {
         let result: IAcceptedEnvelopeRecipientDispatchResult;
-        if (entry.action.type === 'store') {
+        if (entry.action.type === 'store' || entry.action.type === 'deliver') {
+          // Terminal local deliveries: the consumer's durably persisted copy
+          // of the accepted envelope IS the delivery. Nothing is enqueued.
+          if (entry.action.type === 'deliver' && entry.localDomain === null) {
+            // Pre-9.x plans could contain relay-intended deliver entries.
+            // Deliver never relays, so fail loudly instead of dropping.
+            throw new Error(
+              `Deliver action for ${entry.recipient} has no local domain; deliver actions never relay`,
+            );
+          }
           result = { ...commonResult, status: 'stored' };
         } else {
           parsedEmail ||= await this.createEmailFromBuffer(rawCopy, baseSession);
@@ -2298,10 +2346,13 @@ export class UnifiedEmailServer extends EventEmitter {
         return;
       }
 
-      const hasStoreRoute = resolvedRecipientRoutes.some(
-        (resolution) => resolution.route?.action.type === 'store',
+      // `store` and `deliver` are both terminal local deliveries: the
+      // envelope must be durably owned by the consumer before SMTP 250.
+      const hasDurableLocalRoute = resolvedRecipientRoutes.some(
+        (resolution) => resolution.route?.action.type === 'store'
+          || resolution.route?.action.type === 'deliver',
       );
-      if (hasStoreRoute) {
+      if (hasDurableLocalRoute) {
         try {
           await this.acceptDurableEnvelope(
             email,
@@ -2807,6 +2858,23 @@ export class UnifiedEmailServer extends EventEmitter {
     return routes;
   }
 
+  /**
+   * Server-level action policy for a single route. A `deliver` action is a
+   * terminal local delivery owned by the durable `hooks.onAcceptEnvelope`
+   * acceptance path; without that hook the route could only accept-then-fail,
+   * so it is rejected at configuration time instead.
+   */
+  private assertRouteActionServable(route: IEmailRoute): void {
+    if (
+      route.action.type === 'deliver'
+      && !this.options.hooks?.onAcceptEnvelope
+    ) {
+      throw new Error(
+        `Route ${route.name}: action type 'deliver' requires a configured hooks.onAcceptEnvelope durable local-delivery owner`,
+      );
+    }
+  }
+
   /**
    * Update server configuration
    */
@@ -2821,7 +2889,21 @@ export class UnifiedEmailServer extends EventEmitter {
         this.start();
       });
     } else {
-      this.options = { ...this.options, ...options };
+      if (options.routes) {
+        // Validate synchronously against the incoming hook configuration
+        // before any option state is mutated, so invalid routes throw here
+        // instead of surfacing as an unhandled rejection.
+        const previousOptions = this.options;
+        this.options = { ...this.options, ...options };
+        try {
+          this.emailRouter.assertRoutesValid(options.routes);
+        } catch (error) {
+          this.options = previousOptions;
+          throw error;
+        }
+      } else {
+        this.options = { ...this.options, ...options };
+      }
 
       if (options.domains) {
         this.domainRegistry = new DomainRegistry(options.domains, options.defaults || this.options.defaults);
@@ -2837,6 +2919,8 @@ export class UnifiedEmailServer extends EventEmitter {
    * Update email routes
    */
   public updateEmailRoutes(routes: IEmailRoute[]): void {
+    // Fail loudly and synchronously before mutating server options.
+    this.emailRouter.assertRoutesValid(routes);
     this.options.routes = routes;
     this.emailRouter.updateRoutes(routes);
   }

package/ts/mail/routing/interfaces.ts

@@ -43,9 +43,21 @@ export interface IEmailMatch {
  * Action to take when route matches
  */
 export interface IEmailAction {
-  /** Type of action to perform */
+  /**
+   * Type of action to perform.
+   * - `forward`: relay to a configured SMTP host.
+   * - `process`: queue for scanning and outbound MX delivery.
+   * - `deliver`: terminal local delivery through the durable
+   *   `hooks.onAcceptEnvelope` acceptance path. Never relays.
+   * - `store`: terminal local delivery like `deliver`, with explicit
+   *   retention configuration.
+   * - `reject`: refuse with a configurable SMTP error.
+   */
   type: 'forward' | 'deliver' | 'reject' | 'process' | 'store';
-  /** Explicitly permits this route to relay to non-local recipients. */
+  /**
+   * Explicitly permits this route to relay to non-local recipients.
+   * Ignored for `deliver` actions, which are local-only and never relay.
+   */
   allowRelay?: boolean;
   
   /** Forward action configuration */
@@ -124,7 +136,7 @@ export interface IEmailAction {
     }>;
   };
   
-  /** Delivery options (applies to forward/process/deliver) */
+  /** Delivery options (applies to the queue-backed forward/process actions) */
   delivery?: {
     /** Rate limit (messages per minute) */
     rateLimit?: number;