@serve.zone/dcrouter 18.1.0 → 18.2.0

package/ts/db/documents/classes.email-traffic-bucket.doc.ts

@@ -0,0 +1,161 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const DB_OPERATION_TIMEOUT_MS = 5_000;
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+export interface IEmailTrafficBucketCounts {
+  sent: number;
+  received: number;
+  failed: number;
+}
+
+export interface IEmailTrafficBucketSnapshot extends IEmailTrafficBucketCounts {
+  bucketStart: number;
+}
+
+@plugins.smartdata.Collection(() => getDb())
+export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
+  EmailTrafficBucketDoc,
+  EmailTrafficBucketDoc
+> implements IEmailTrafficBucketSnapshot {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public bucketStart!: number;
+
+  @plugins.smartdata.svDb()
+  public sent: number = 0;
+
+  @plugins.smartdata.svDb()
+  public received: number = 0;
+
+  @plugins.smartdata.svDb()
+  public failed: number = 0;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  constructor() {
+    super();
+  }
+
+  private static async getNativeCollection() {
+    const smartdataCollection = (EmailTrafficBucketDoc as typeof EmailTrafficBucketDoc & {
+      collection: plugins.smartdata.SmartdataCollection<EmailTrafficBucketDoc>;
+    }).collection;
+    await smartdataCollection.init();
+    const probe = new EmailTrafficBucketDoc();
+    await smartdataCollection.markUniqueIndexes(probe.uniqueIndexes || []);
+    await smartdataCollection.createRegularIndexes(probe.regularIndexes || []);
+    return smartdataCollection.mongoDbCollection;
+  }
+
+  private static validateSnapshot(snapshotArg: IEmailTrafficBucketSnapshot): void {
+    const counts = [snapshotArg.sent, snapshotArg.received, snapshotArg.failed];
+    if (
+      !Number.isSafeInteger(snapshotArg.bucketStart)
+      || snapshotArg.bucketStart < 0
+      || snapshotArg.bucketStart % 60_000 !== 0
+      || counts.some((count) => !Number.isSafeInteger(count) || count < 0)
+    ) {
+      throw new Error('Invalid email traffic bucket snapshot');
+    }
+  }
+
+  /** Persist retry-safe absolute monotonic counters. */
+  public static async persistAbsolute(snapshotsArg: IEmailTrafficBucketSnapshot[]): Promise<void> {
+    if (snapshotsArg.length === 0) return;
+    if (snapshotsArg.length > 500) {
+      throw new Error('EmailTrafficBucketDoc.persistAbsolute accepts at most 500 buckets');
+    }
+    for (const snapshot of snapshotsArg) {
+      EmailTrafficBucketDoc.validateSnapshot(snapshot);
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    const now = Date.now();
+    const updatedAt = new Date(now).toISOString();
+    await collection.bulkWrite(
+      snapshotsArg.map((snapshot) => ({
+        updateOne: {
+          filter: { bucketStart: snapshot.bucketStart },
+          update: {
+            $max: {
+              sent: snapshot.sent,
+              received: snapshot.received,
+              failed: snapshot.failed,
+            },
+            $set: {
+              updatedAt: now,
+              _updatedAt: updatedAt,
+            },
+            $setOnInsert: {
+              id: `email-traffic-${snapshot.bucketStart}`,
+              bucketStart: snapshot.bucketStart,
+              createdAt: now,
+              _createdAt: updatedAt,
+            },
+          },
+          upsert: true,
+        },
+      })),
+      { ordered: false, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+    );
+  }
+
+  public static async loadSince(cutoffArg: number): Promise<IEmailTrafficBucketSnapshot[]> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('EmailTrafficBucketDoc.loadSince requires a valid cutoff');
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    const cursor = collection
+      .find(
+        { bucketStart: { $gte: cutoffArg } },
+        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      )
+      .sort({ bucketStart: 1 });
+    try {
+      const rows = await cursor.toArray();
+      return rows.map((row) => ({
+        bucketStart: Number(row.bucketStart),
+        sent: Number(row.sent || 0),
+        received: Number(row.received || 0),
+        failed: Number(row.failed || 0),
+      }));
+    } finally {
+      await cursor.close({ timeoutMS: DB_OPERATION_TIMEOUT_MS });
+    }
+  }
+
+  public static async pruneBefore(cutoffArg: number): Promise<number> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('EmailTrafficBucketDoc.pruneBefore requires a valid cutoff');
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    let deletedCount = 0;
+    while (true) {
+      const rows = await collection
+        .find(
+          { bucketStart: { $lt: cutoffArg } },
+          { projection: { _id: 1 }, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+        )
+        .sort({ bucketStart: 1, _id: 1 })
+        .limit(500)
+        .toArray();
+      if (rows.length === 0) break;
+      const result = await collection.deleteMany(
+        { _id: { $in: rows.map((row) => row._id) } },
+        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      );
+      deletedCount += result.deletedCount;
+      if (rows.length < 500) break;
+    }
+    return deletedCount;
+  }
+}

package/ts/db/documents/index.ts

@@ -4,6 +4,8 @@ export * from './classes.cached.ip.reputation.js';
 export * from './classes.ip-intelligence.doc.js';
 export * from './classes.security-block-rule.doc.js';
 export * from './classes.security-policy-audit.doc.js';
+export * from './classes.authentication-event.doc.js';
+export * from './classes.email-traffic-bucket.doc.js';
 
 // Config document classes
 export * from './classes.route.doc.js';

package/ts/email/classes.accepted-email-spool.ts

@@ -8,10 +8,13 @@ import type {
 import { AcceptEnvelopeRejectionError } from '@push.rocks/smartmta';
 import type {
   Email,
+  IAcceptedEnvelopeDispatchMetadata,
+  IAcceptedEnvelopeRecipientPlan,
   IAcceptEnvelopeContext,
   IExtendedSmtpSession,
   IMessageAcceptanceContext,
   IMessageAcceptanceDecision,
+  IResolvedRecipientRoute,
   UnifiedEmailServer,
 } from '@push.rocks/smartmta';
 import type { DcRouter } from '../classes.dcrouter.js';
@@ -76,6 +79,9 @@ const ACCEPTED_EMAIL_SPOOL_BATCH_SIZE = 25;
 const ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS = 30_000;
 /** Retention for catch-all stored inbound mail (30 days). */
 const INBOUND_STORE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Redispatch attempts for the non-store recipients of a durable envelope. */
+const ENVELOPE_DISPATCH_MAX_ATTEMPTS = 10;
+const ENVELOPE_DISPATCH_RETRY_DELAY_MS = 5 * 60_000;
 
 /**
  * Permanent per-email storage failure: the raw RFC822 payload of an accepted
@@ -136,8 +142,32 @@ type TStoredCachedEmailSession = {
   };
 };
 
+/**
+ * Persisted per-recipient dispatch state for a durably accepted envelope.
+ * Holds everything needed to replay `dispatchAcceptedEnvelope` byte-identically:
+ * upstream fingerprints each recipient over the raw message, the metadata and
+ * the plan entry, so a replay reconstructed from anything else would be refused
+ * as an idempotency-key reuse instead of retrying.
+ */
+type TStoredEnvelopeDispatch = {
+  plan: IAcceptedEnvelopeRecipientPlan[];
+  metadata: IAcceptedEnvelopeDispatchMetadata;
+  attempts: number;
+  results?: Array<{
+    recipient: string;
+    status: string;
+    message?: string;
+    smtpCode?: number;
+  }>;
+  pendingRecipients?: string[];
+  /** Set once retries are exhausted; the row stops being redispatched. */
+  abandonedAt?: string;
+};
+
 type TStoredCachedEmailRouteData = {
+  acceptance?: string;
   session?: TStoredCachedEmailSession;
+  envelopeDispatch?: TStoredEnvelopeDispatch;
   smartMta?: {
     status?: 'queued' | 'deferred' | 'delivered' | 'failed';
     nextAttempt?: string;
@@ -185,6 +215,54 @@ export class AcceptedEmailSpool {
 
   constructor(private dcRouterRef: DcRouter) {}
 
+  /**
+   * Direction is decided by the RECIPIENT, never by whether the session
+   * authenticated. Authentication grants permission to relay; it does not make
+   * a message addressed to a mailbox we host into outbound mail. A message with
+   * at least one locally hosted recipient is inbound — a local mailbox receives
+   * it — and only an envelope addressed exclusively to remote recipients is
+   * outbound.
+   *
+   * `IResolvedRecipientRoute.localDomain` is smartmta's own per-recipient
+   * verdict (non-null exactly when the domain registry hosts the domain), so
+   * the classification uses the same truth the routing decision used. When an
+   * acceptance context carries no resolution the envelope recipients are
+   * classified against the live registry instead — never against the session,
+   * which is the mistake being fixed.
+   */
+  private deriveDirectionFromResolvedRoutes(
+    resolvedRecipientRoutes: readonly IResolvedRecipientRoute[] | undefined,
+    envelopeRecipientsArg: readonly string[],
+  ): TCachedEmailDirection {
+    if (resolvedRecipientRoutes?.length) {
+      return resolvedRecipientRoutes.some((resolution) => !!resolution.localDomain)
+        ? 'inbound'
+        : 'outbound';
+    }
+    return this.deriveDirectionFromRecipients(envelopeRecipientsArg);
+  }
+
+  /**
+   * Recipient-derived direction for programmatic submitters, which have no SMTP
+   * recipient resolution to consult. Falls back to the live domain registry.
+   */
+  private deriveDirectionFromRecipients(recipientsArg: readonly string[]): TCachedEmailDirection {
+    const domainRegistry = this.dcRouterRef.emailServer?.domainRegistry;
+    if (!domainRegistry) {
+      // Without the registry there is no recipient truth to classify against.
+      // Programmatic submission is relay by construction, so outbound is the
+      // honest label rather than guessing from the session.
+      return 'outbound';
+    }
+    for (const recipient of recipientsArg) {
+      const domain = recipient.split('@')[1]?.trim().toLowerCase();
+      if (domain && domainRegistry.isDomainRegistered(domain)) {
+        return 'inbound';
+      }
+    }
+    return 'outbound';
+  }
+
   public async acceptMessage(
     context: IMessageAcceptanceContext,
     processAfterAccept = true,
@@ -218,7 +296,10 @@ export class AcceptedEmailSpool {
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
-    cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
+    cachedEmail.direction = this.deriveDirectionFromResolvedRoutes(
+      context.resolvedRecipientRoutes,
+      envelopeRecipients.length > 0 ? envelopeRecipients : cachedEmail.to,
+    );
     cachedEmail.acceptedAt = Date.now();
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date().toISOString(),
@@ -256,6 +337,7 @@ export class AcceptedEmailSpool {
       await this.notifyEmailQueuePersisted(cachedEmail, 'email-accepted-without-queue');
     }
 
+    this.trackAcceptedInboundEmail(cachedEmail);
     return {
       accepted: true,
       smtpCode: 250,
@@ -287,7 +369,7 @@ export class AcceptedEmailSpool {
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
     cachedEmail.direction = optionsArg.direction
-      ?? (optionsArg.session.authenticated ? 'outbound' : 'inbound');
+      ?? this.deriveDirectionFromRecipients(optionsArg.envelope.rcptTo);
     cachedEmail.acceptedAt = Date.now();
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date().toISOString(),
@@ -319,6 +401,7 @@ export class AcceptedEmailSpool {
       await this.notifyEmailQueuePersisted(cachedEmail, 'raw-email-accepted-without-queue');
     }
 
+    this.trackAcceptedInboundEmail(cachedEmail);
     return {
       accepted: true,
       spoolItemId: cachedEmail.id,
@@ -377,7 +460,10 @@ export class AcceptedEmailSpool {
       cachedEmail.id,
     );
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
-    cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
+    cachedEmail.direction = this.deriveDirectionFromResolvedRoutes(
+      context.resolvedRecipientRoutes,
+      context.envelope.rcptTo,
+    );
     cachedEmail.acceptedAt = startedAtMs;
 
     if (acceptance.dmarcReject) {
@@ -413,6 +499,15 @@ export class AcceptedEmailSpool {
     } else {
       cachedEmail.status = 'accepted';
     }
+    if (nonStoreEntries.length > 0) {
+      // Relay recipients are dispatched after this row is committed. Park the
+      // row in a status the spool actually scans so a crash between the commit
+      // and the dispatch leaves those recipients recoverable instead of stranded
+      // in a terminal-looking 'accepted' row. The dispatch outcome settles it
+      // straight back to the acceptance status.
+      cachedEmail.status = 'deferred';
+      cachedEmail.nextAttempt = new Date(Date.now() + ENVELOPE_DISPATCH_RETRY_DELAY_MS);
+    }
     cachedEmail.deliveredAt = new Date();
     cachedEmail.setTTL(INBOUND_STORE_RETENTION_MS);
     cachedEmail.appendSmtpTransaction(this.buildInboundTransaction(context, cachedEmail.id, {
@@ -422,6 +517,7 @@ export class AcceptedEmailSpool {
       doubts: acceptance.doubts,
       startedAtMs,
     }));
+    const dispatchMetadata = this.buildEnvelopeDispatchMetadata(context);
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date(startedAtMs).toISOString(),
       acceptance: 'durable-envelope',
@@ -432,6 +528,18 @@ export class AcceptedEmailSpool {
         source: entry.source,
         actionType: entry.action.type,
       })),
+      // Persisted BEFORE the SMTP 250, so a dispatch failure for the non-store
+      // recipients is recoverable instead of being lost with the process.
+      ...(nonStoreEntries.length > 0
+        ? {
+          envelopeDispatch: {
+            plan: [...plan],
+            metadata: dispatchMetadata,
+            attempts: 0,
+            pendingRecipients: nonStoreEntries.map((entry) => entry.recipient),
+          } satisfies TStoredEnvelopeDispatch,
+        }
+        : {}),
       session: {
         id: session.id,
         remoteAddress: session.remoteAddress,
@@ -459,27 +567,198 @@ export class AcceptedEmailSpool {
     }
 
     if (nonStoreEntries.length > 0) {
-      const dispatchResult = await emailServer.dispatchAcceptedEnvelope(
-        context.rawMessage,
-        plan,
-        {
-          mailFrom: context.envelope.mailFrom,
-          session: {
-            id: session.id,
-            remoteAddress: session.remoteAddress,
-            clientHostname: session.clientHostname,
-            secure: !!session.secure,
-            authenticated: !!session.authenticated,
-          },
-        },
-      );
-      const failed = dispatchResult.results.filter(
-        (result) => result.status === 'failed' || result.status === 'rejected',
+      await this.dispatchEnvelopeRecipients(cachedEmail, persistedRawMessage, emailServer);
+    }
+    this.trackAcceptedInboundEmail(cachedEmail);
+  }
+
+  /**
+   * Session metadata for `dispatchAcceptedEnvelope`. It feeds the per-recipient
+   * idempotency fingerprint, so it must be JSON-round-trip stable: a replay
+   * reconstructed from persisted state has to produce byte-identical metadata
+   * or upstream refuses it as an idempotency-key reuse.
+   */
+  private buildEnvelopeDispatchMetadata(
+    context: IAcceptEnvelopeContext,
+  ): IAcceptedEnvelopeDispatchMetadata {
+    const session = context.session;
+    return {
+      mailFrom: context.envelope.mailFrom,
+      session: {
+        id: session.id || '',
+        remoteAddress: session.remoteAddress || '',
+        clientHostname: session.clientHostname || '',
+        secure: !!session.secure,
+        authenticated: !!session.authenticated,
+      },
+    };
+  }
+
+  /**
+   * Dispatch (or redispatch) the non-store recipients of a durably accepted
+   * envelope.
+   *
+   * The raw bytes handed to upstream are the exact bytes persisted for this row,
+   * because upstream fingerprints every recipient over the raw message: a later
+   * replay with different bytes would be rejected as an idempotency-key reuse
+   * rather than retried. Recipients that already succeeded are short-circuited
+   * by upstream's checkpoints, and `failed` results are deliberately not
+   * checkpointed upstream, so an identical replay retries exactly those.
+   *
+   * A `failed` recipient leaves the row non-terminal so the spool retries it;
+   * a `rejected` recipient is a permanent per-recipient refusal and is recorded
+   * durably instead of being retried. Either way the outcome is persisted — a
+   * relay recipient is never silently dropped after the SMTP 250.
+   */
+  private async dispatchEnvelopeRecipients(
+    cachedEmailArg: CachedEmail,
+    rawMessageArg: string,
+    emailServerArg: UnifiedEmailServer,
+  ): Promise<void> {
+    const routeData = this.parseCachedEmailRouteData(cachedEmailArg);
+    const envelopeDispatch = routeData.envelopeDispatch;
+    if (!envelopeDispatch || envelopeDispatch.abandonedAt) return;
+
+    const attempts = (envelopeDispatch.attempts || 0) + 1;
+    let dispatchResults: Array<{
+      recipient: string;
+      status: string;
+      message?: string;
+      smtpCode?: number;
+    }>;
+    try {
+      const dispatchResult = await emailServerArg.dispatchAcceptedEnvelope(
+        plugins.buffer.Buffer.from(rawMessageArg, 'utf8'),
+        envelopeDispatch.plan,
+        envelopeDispatch.metadata,
       );
-      if (failed.length > 0) {
-        logger.log('warn', `Durable envelope ${cachedEmail.id}: ${failed.length}/${dispatchResult.results.length} non-store recipients failed dispatch: ${failed.map((result) => `${result.recipient}=${result.message || result.status}`).join('; ')}`);
+      dispatchResults = dispatchResult.results.map((result) => ({
+        recipient: result.recipient,
+        status: result.status,
+        ...(result.message ? { message: result.message } : {}),
+        ...(result.smtpCode !== undefined ? { smtpCode: result.smtpCode } : {}),
+      }));
+    } catch (error: unknown) {
+      // A whole-call failure (missing managed queue storage, malformed
+      // checkpoint) is retried the same way a per-recipient failure is.
+      dispatchResults = envelopeDispatch.plan
+        .filter((entry) => entry.action.type !== 'store' && entry.action.type !== 'deliver')
+        .map((entry) => ({
+          recipient: entry.recipient,
+          status: 'failed',
+          message: (error as Error).message,
+        }));
+    }
+
+    const retryable = dispatchResults.filter((result) => result.status === 'failed');
+    const rejected = dispatchResults.filter((result) => result.status === 'rejected');
+    const exhausted = retryable.length > 0 && attempts >= ENVELOPE_DISPATCH_MAX_ATTEMPTS;
+
+    await this.persistEnvelopeDispatchOutcome(cachedEmailArg.id, {
+      attempts,
+      results: dispatchResults,
+      pendingRecipients: exhausted ? [] : retryable.map((result) => result.recipient),
+      abandoned: exhausted,
+    });
+
+    if (rejected.length > 0) {
+      logger.log('error', `Durable envelope ${cachedEmailArg.id}: ${rejected.length} relay recipient(s) permanently refused: ${rejected.map((result) => `${result.recipient}=${result.smtpCode || 550} ${result.message || 'rejected'}`).join('; ')}`);
+    }
+    if (exhausted) {
+      logger.log('error', `Durable envelope ${cachedEmailArg.id}: giving up on ${retryable.length} relay recipient(s) after ${attempts} dispatch attempts: ${retryable.map((result) => `${result.recipient}=${result.message || 'failed'}`).join('; ')}`);
+    } else if (retryable.length > 0) {
+      logger.log('warn', `Durable envelope ${cachedEmailArg.id}: ${retryable.length} relay recipient(s) failed dispatch (attempt ${attempts}/${ENVELOPE_DISPATCH_MAX_ATTEMPTS}), scheduled for redispatch: ${retryable.map((result) => `${result.recipient}=${result.message || 'failed'}`).join('; ')}`);
+    }
+  }
+
+  /**
+   * Persist a dispatch attempt's outcome on the durable-envelope row.
+   *
+   * The row's status tracks the stored envelope, not the relay: it goes
+   * `deferred` only while relay recipients still need a redispatch, and returns
+   * to its acceptance status once none do. Relay progress itself lives in
+   * `routeData.envelopeDispatch`, so a relay failure can never mark a row whose
+   * local copy stored successfully as failed.
+   */
+  private async persistEnvelopeDispatchOutcome(
+    cachedEmailIdArg: string,
+    outcomeArg: {
+      attempts: number;
+      results: Array<{ recipient: string; status: string; message?: string; smtpCode?: number }>;
+      pendingRecipients: string[];
+      abandoned: boolean;
+    },
+  ): Promise<void> {
+    await this.runCachedEmailUpdate(cachedEmailIdArg, async () => {
+      const cachedEmail = await CachedEmail.findById(cachedEmailIdArg);
+      if (!cachedEmail) return;
+      const routeData = this.parseCachedEmailRouteData(cachedEmail);
+      if (!routeData.envelopeDispatch) return;
+      routeData.envelopeDispatch = {
+        ...routeData.envelopeDispatch,
+        attempts: outcomeArg.attempts,
+        results: outcomeArg.results,
+        pendingRecipients: outcomeArg.pendingRecipients,
+        ...(outcomeArg.abandoned ? { abandonedAt: new Date().toISOString() } : {}),
+      };
+      cachedEmail.routeData = JSON.stringify(routeData);
+
+      const stillPending = outcomeArg.pendingRecipients.length > 0;
+      const acceptanceStatus = cachedEmail.lastError && !stillPending ? 'flagged' : 'accepted';
+      if (stillPending) {
+        cachedEmail.status = 'deferred';
+        cachedEmail.nextAttempt = new Date(Date.now() + ENVELOPE_DISPATCH_RETRY_DELAY_MS);
+      } else if (cachedEmail.status === 'deferred') {
+        cachedEmail.status = acceptanceStatus;
+        cachedEmail.nextAttempt = new Date();
       }
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(
+        cachedEmail,
+        stillPending ? 'envelope-dispatch-deferred' : 'envelope-dispatch-settled',
+      );
+    });
+  }
+
+  /**
+   * Take exclusive ownership of a durably accepted envelope row in the spool.
+   *
+   * Runs before live-queue postponement and before the normal spool handoff: a
+   * relay sibling that did enqueue would otherwise postpone this row forever,
+   * and the normal handoff would re-run route evaluation and duplicate a
+   * delivery the stored copy already fulfilled.
+   */
+  private async handleDurableEnvelopeRow(
+    cachedEmailArg: CachedEmail,
+    emailServerArg: UnifiedEmailServer,
+  ): Promise<boolean> {
+    if (!this.isDurableEnvelopeRow(cachedEmailArg)) return false;
+    const envelopeDispatch = this.parseCachedEmailRouteData(cachedEmailArg).envelopeDispatch;
+
+    if (envelopeDispatch?.pendingRecipients?.length && !envelopeDispatch.abandonedAt) {
+      const rawMessage = await this.readRawMessage(cachedEmailArg);
+      await this.dispatchEnvelopeRecipients(
+        cachedEmailArg,
+        rawMessage.toString('utf8'),
+        emailServerArg,
+      );
+      return true;
+    }
+
+    // Nothing left to dispatch: settle the row back onto its acceptance status
+    // so a fully dispatched envelope does not linger as deferred.
+    if (cachedEmailArg.status === 'deferred') {
+      cachedEmailArg.status = cachedEmailArg.lastError ? 'flagged' : 'accepted';
+      cachedEmailArg.nextAttempt = new Date();
+      await cachedEmailArg.save();
+      await this.notifyEmailQueuePersisted(cachedEmailArg, 'envelope-dispatch-settled');
     }
+    return true;
+  }
+
+  private trackAcceptedInboundEmail(cachedEmailArg: CachedEmail): void {
+    if (cachedEmailArg.direction !== 'inbound') return;
+    this.dcRouterRef.metricsManager?.trackEmailReceived(cachedEmailArg.from);
   }
 
   /**
@@ -772,6 +1051,11 @@ export class AcceptedEmailSpool {
           break;
         }
         try {
+          // Durable envelopes are owned by the accepted-envelope dispatch path,
+          // never by the route-evaluating handoff below.
+          if (await this.handleDurableEnvelopeRow(cachedEmail, emailServer)) {
+            continue;
+          }
           if (await this.postponeLiveSmartMtaOwnedEmail(cachedEmail, emailServer)) {
             continue;
           }
@@ -946,6 +1230,15 @@ export class AcceptedEmailSpool {
       this.appendSmtpTransaction(cachedEmail, transaction);
     }
     this.updateSmartMtaRouteData(cachedEmail, item, status);
+    if (this.isDurableEnvelopeRow(cachedEmail)) {
+      // The row represents the durably accepted and stored envelope; the queue
+      // item only covers its relay recipients. Record the relay telemetry but
+      // never let a relay outcome overwrite the stored copy's status — a failed
+      // relay must not mark a successfully stored envelope as failed.
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, `envelope-relay-${status}`);
+      return;
+    }
     if (status === 'delivered') {
       cachedEmail.markDelivered();
     } else if (status === 'failed') {
@@ -1008,6 +1301,11 @@ export class AcceptedEmailSpool {
     return cachedEmail.status === 'delivered' || cachedEmail.status === 'failed';
   }
 
+  /** Whether this row was durably accepted through the envelope acceptance path. */
+  private isDurableEnvelopeRow(cachedEmail: CachedEmail): boolean {
+    return this.parseCachedEmailRouteData(cachedEmail).acceptance === 'durable-envelope';
+  }
+
   /** The CachedEmail row a live queue item was spooled from (via the cache-id header). */
   public getCachedEmailIdFromQueueItem(item: TSmartMtaQueueItemLike): string | undefined {
     return this.getHeaderValue(item.processingResult?.headers, DCROUTER_CACHE_ID_HEADER)

package/ts/email/classes.workapp-mail-manager.ts

@@ -1128,7 +1128,10 @@ export class WorkAppMailManager {
       spoolItem: {
         id: cachedEmailArg.id,
         owner,
-        direction: this.getCachedEmailSessionUsername(cachedEmailArg) ? 'outbound' : 'inbound',
+        // The persisted field is the single source of truth: it is derived from
+        // the recipients at acceptance, whereas re-deriving from the session
+        // username here reproduced the "authenticated means outbound" mistake.
+        direction: cachedEmailArg.direction,
         status,
         envelope: {
           mailFrom: cachedEmailArg.from,