@serve.zone/platformclient 3.0.1 → 4.1.0

package/ts/email/classes.emailconnector.ts

@@ -1,4 +1,9 @@
 import type { SzPlatformClient } from '../classes.platformclient.js';
+import {
+  SzCoreMailConnector,
+  type ISzCoreMailInboundFetchResult,
+  type ISzCoreMailInboundPollOptions,
+} from '../coremail/classes.coremailconnector.js';
 import * as plugins from '../plugins.js';
 
 import { logger } from '../logger.js';
@@ -23,6 +28,16 @@ export interface IServiceMailTypedCredentials {
   addressToken?: string;
 }
 
+export interface IServiceMailCoreMailCredentials {
+  from: string;
+  endpointUrl: string;
+  bindingId: string;
+  credentialId: string;
+  credentialVersion: number;
+  credentialSecret: string;
+  addressToken?: string;
+}
+
 export interface IServiceMailStatus {
   ready: boolean;
   from?: string;
@@ -30,10 +45,12 @@ export interface IServiceMailStatus {
   port?: number;
   tlsMode?: TServiceMailTlsMode;
   typedUrl?: string;
-  transport?: 'typedsocket' | 'smtp' | 'none';
+  transport?: 'coremail' | 'typedsocket' | 'smtp' | 'none';
   usernameConfigured: boolean;
   passwordConfigured: boolean;
   typedCredentialConfigured?: boolean;
+  coreMailConfigured?: boolean;
+  coreMailEndpointUrl?: string;
   smtpReady?: boolean;
   missing: string[];
 }
@@ -73,6 +90,84 @@ export class ServiceMailSubmissionError extends Error {
   }
 }
 
+/**
+ * CoreMail error codes that @serve.zone/interfaces 30.13.0 also carries in
+ * TMailSubmissionErrorCode. These pass through by identity, so an application
+ * branching on ServiceMailSubmissionError.code sees the code CoreMail actually
+ * produced. Both entries of each pair are spelled out and the array is typed on
+ * both unions, so dropping a member from either side is a compile error here
+ * rather than a silent downgrade to the generic failure at runtime.
+ */
+const coreMailPassThroughErrorCodes: ReadonlyArray<
+  plugins.servezoneInterfaces.data.TCoreMailErrorCode
+  & plugins.servezoneInterfaces.data.TMailSubmissionErrorCode
+> = [
+  'AUTHENTICATION_FAILED',
+  'CAPABILITY_DENIED',
+  'INVALID_REQUEST',
+  'INVALID_MAILBOX',
+  'INVALID_SENDER',
+  'INVALID_RECIPIENT',
+  'INVALID_HEADER',
+  'PAYLOAD_LIMIT_EXCEEDED',
+  'QUOTA_EXCEEDED',
+  'IDEMPOTENCY_CONFLICT',
+  'STATE_CONFLICT',
+  'NOT_FOUND',
+];
+
+/**
+ * Deliberate departures from identity. Empty since interfaces 30.13.0: the
+ * only former entry was INVALID_HEADER -> REPLY_TO_FIELD_HEADER_CONFLICT, which
+ * existed solely because INVALID_HEADER had no member of its own. It now has
+ * one, and remapping would describe a generic invalid-header rejection as a
+ * reply-to conflict. Kept as the declared seam so that if the two unions ever
+ * diverge again the exception has a documented home instead of being open-coded.
+ */
+const coreMailRemappedErrorCodes: Partial<
+  Record<
+    plugins.servezoneInterfaces.data.TCoreMailErrorCode,
+    plugins.servezoneInterfaces.data.TMailSubmissionErrorCode
+  >
+> = {};
+
+/**
+ * Resolves one CoreMail code onto the app-facing union, or undefined when the
+ * code has no representation there (the transfer, delivery, gateway and
+ * reconciliation families). Those become a generic Error carrying the code.
+ */
+const resolveSubmissionErrorCode = (
+  codeArg: plugins.servezoneInterfaces.data.TCoreMailErrorCode,
+): plugins.servezoneInterfaces.data.TMailSubmissionErrorCode | undefined => {
+  const remapped = coreMailRemappedErrorCodes[codeArg];
+  if (remapped) return remapped;
+  return coreMailPassThroughErrorCodes.find((candidateArg) => candidateArg === codeArg);
+};
+
+/**
+ * TCoreMailSubmissionState -> TMailSpoolStatus.
+ * 'accepted' | 'queued' | 'delivering' | 'delivered' | 'deferred' | 'failed' |
+ * 'deadLettered' exist verbatim in both unions and pass through. CoreMail's
+ * three pre-acceptance states ('preparing' | 'uploading' | 'ready') have no
+ * spool counterpart and collapse onto 'queued'; the spool-only 'rejected' is
+ * never produced by CoreMail.
+ */
+const coreMailStateToSpoolStatus: Record<
+  plugins.servezoneInterfaces.data.TCoreMailSubmissionState,
+  plugins.servezoneInterfaces.data.TMailSpoolStatus
+> = {
+  preparing: 'queued',
+  uploading: 'queued',
+  ready: 'queued',
+  accepted: 'accepted',
+  queued: 'queued',
+  delivering: 'delivering',
+  delivered: 'delivered',
+  deferred: 'deferred',
+  failed: 'failed',
+  deadLettered: 'deadLettered',
+};
+
 export interface IServiceMailSendResult {
   messageId?: string;
   spoolItemId?: string;
@@ -106,12 +201,18 @@ export class SzEmailConnector {
   private mailTypedSocketUrl?: string;
   private mailTypedSocketPromise?: Promise<plugins.typedsocket.TypedSocket>;
   private mailTypedSocketAbortController?: AbortController;
-  private mailTypedSocketStatusSubscription?: { unsubscribe: () => void };
+  private readonly mailRouter = new plugins.typedrequest.TypedRouter();
+  private readonly restorationOperations = new Set<Promise<void>>();
   private inboundHandler?: TServiceMailInboundHandler;
   private inboundTypedHandlerRegistered = false;
   private inboundEndpointRegistrations = new Set<string>();
-  private inboundEndpointReplayPromise?: Promise<void>;
-  private readonly inboundEndpointReplayRetryDelaysMs = [500, 1000, 2000, 5000];
+  private coreMailInboundPollOptions: ISzCoreMailInboundPollOptions = {};
+  /**
+   * Connectors this email connector created and therefore owns, keyed by the
+   * value-free binding identity. The client's shared connector is never in here
+   * — it is owned by SzPlatformClient and stopped there.
+   */
+  private ownedCoreMailConnectors = new Map<string, SzCoreMailConnector>();
 
   constructor(platformClientRefArg: SzPlatformClient) {
     this.platformClientRef = platformClientRefArg;
@@ -136,7 +237,7 @@ export class SzEmailConnector {
     }
 
     const typedRequest =
-      this.platformClientRef.typedsocket.createTypedRequest<plugins.servezoneInterfaces.platform.email.IReq_SendEmail>(
+      this.platformClientRef.requireTypedSocket().createTypedRequest<plugins.servezoneInterfaces.platform.email.IReq_SendEmail>(
         'sendEmail'
       );
     const response = await typedRequest.fire(optionsArg);
@@ -169,6 +270,37 @@ export class SzEmailConnector {
     const fromMissing = env.from ? [] : [missingPrefix ? `MAIL_${missingPrefix}_FROM` : 'MAIL_FROM'];
     const typedReady = fromMissing.length === 0 && typedMissing.length === 0;
     const smtpReady = fromMissing.length === 0 && smtpMissing.length === 0;
+
+    // CoreMail outranks the dcrouter-direct transports when its group resolves.
+    const coreMailToken = useDefaultEnv ? undefined : token;
+    const scopedCoreMail = coreMailToken ? await this.readCoreMailEnv(coreMailToken) : undefined;
+    const hasScopedCoreMail = Boolean(scopedCoreMail && Object.values(scopedCoreMail).some(Boolean));
+    const coreMailEnv = hasScopedCoreMail ? scopedCoreMail! : await this.readCoreMailEnv();
+    const coreMailPresent = Object.values(coreMailEnv).some(Boolean);
+    const coreMailMissing = coreMailPresent
+      ? this.listMissingCoreMailEnvNames(coreMailEnv, hasScopedCoreMail ? coreMailToken : undefined)
+      : [];
+    const coreMailReady = coreMailPresent
+      && coreMailMissing.length === 0
+      && fromMissing.length === 0;
+    if (coreMailPresent) {
+      return {
+        ready: coreMailReady,
+        from: env.from,
+        host: env.smtpHost,
+        port,
+        tlsMode,
+        typedUrl: env.typedUrl,
+        transport: coreMailReady ? 'coremail' : smtpReady ? 'smtp' : 'none',
+        usernameConfigured: Boolean(env.smtpUsername),
+        passwordConfigured: Boolean(env.smtpPassword),
+        typedCredentialConfigured: Boolean(env.apiCredentialId && env.apiCredentialSecret),
+        coreMailConfigured: coreMailReady,
+        coreMailEndpointUrl: coreMailEnv.url,
+        smtpReady,
+        missing: coreMailReady ? [] : [...fromMissing, ...coreMailMissing],
+      };
+    }
     return {
       ready: typedReady,
       from: env.from,
@@ -231,6 +363,11 @@ export class SzEmailConnector {
       return { messageId: 'debug' };
     }
 
+    const coreMailCredentials = await this.getCoreMailCredentials(optionsArg.from);
+    if (coreMailCredentials) {
+      return await this.sendMailViaCoreMail(optionsArg, coreMailCredentials);
+    }
+
     const credentials = await this.getServiceMailTypedCredentials(optionsArg.from);
     const typedSocket = await this.getMailTypedSocket(credentials.typedUrl);
     const request = typedSocket.createTypedRequest<plugins.servezoneInterfaces.requests.mail.IReq_EnqueueMail>('enqueueMail');
@@ -274,6 +411,212 @@ export class SzEmailConnector {
     };
   }
 
+  private async createCoreMailSha256(
+    bytesArg: Uint8Array,
+  ): Promise<plugins.servezoneInterfaces.data.TCoreMailSha256> {
+    const source = new Uint8Array(bytesArg.byteLength);
+    source.set(bytesArg);
+    const digest = new Uint8Array(
+      await globalThis.crypto.subtle.digest('SHA-256', source.buffer),
+    );
+    return `sha256:${Array.from(digest)
+      .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+      .join('')}`;
+  }
+
+  private toCoreMailMailbox(
+    addressArg: string,
+  ): plugins.servezoneInterfaces.data.ICoreMailMailbox {
+    const address = String(addressArg || '').trim();
+    if (!address) throw new Error('CoreMail recipients must be non-empty addresses');
+    return { address };
+  }
+
+  /**
+   * Bodies and attachments become uploadable parts. CoreMail owns the MIME
+   * framing, so text/html/attachments are separate descriptors rather than one
+   * serialized message, and every descriptor carries a client-computed digest.
+   */
+  private async buildCoreMailParts(optionsArg: IServiceMailSendOptions): Promise<Array<{
+    descriptor: plugins.servezoneInterfaces.data.ICoreMailContentDescriptor;
+    bytes: Uint8Array;
+  }>> {
+    const limits = plugins.servezoneInterfaces.data.coreMailLimits;
+    const encoder = new TextEncoder();
+    const parts: Array<{
+      descriptor: plugins.servezoneInterfaces.data.ICoreMailContentDescriptor;
+      bytes: Uint8Array;
+    }> = [];
+
+    const pushPart = async (
+      partIdArg: string,
+      kindArg: plugins.servezoneInterfaces.data.TCoreMailPartKind,
+      contentTypeArg: string,
+      bytesArg: Uint8Array,
+      filenameArg?: string,
+    ) => {
+      parts.push({
+        descriptor: {
+          partId: partIdArg,
+          kind: kindArg,
+          contentType: contentTypeArg,
+          ...(filenameArg ? { filename: filenameArg } : {}),
+          sha256: await this.createCoreMailSha256(bytesArg),
+          lengthBytes: bytesArg.byteLength,
+        },
+        bytes: bytesArg,
+      });
+    };
+
+    if (optionsArg.text) {
+      const bytes = encoder.encode(optionsArg.text);
+      if (bytes.byteLength > limits.textPartBytes) {
+        throw new Error(`CoreMail text part exceeds ${limits.textPartBytes} bytes`);
+      }
+      await pushPart('text', 'text', 'text/plain; charset=utf-8', bytes);
+    }
+    if (optionsArg.html) {
+      const bytes = encoder.encode(optionsArg.html);
+      if (bytes.byteLength > limits.htmlPartBytes) {
+        throw new Error(`CoreMail html part exceeds ${limits.htmlPartBytes} bytes`);
+      }
+      await pushPart('html', 'html', 'text/html; charset=utf-8', bytes);
+    }
+
+    const attachments = optionsArg.attachments || [];
+    if (attachments.length > limits.attachmentCount) {
+      throw new Error(`CoreMail accepts at most ${limits.attachmentCount} attachments`);
+    }
+    let aggregateBytes = 0;
+    for (const [index, attachment] of attachments.entries()) {
+      const bytes = typeof attachment.content === 'string'
+        ? encoder.encode(attachment.content)
+        : attachment.content;
+      if (bytes.byteLength > limits.attachmentBytes) {
+        throw new Error(
+          `CoreMail attachment ${attachment.filename} exceeds ${limits.attachmentBytes} bytes`,
+        );
+      }
+      aggregateBytes += bytes.byteLength;
+      if (aggregateBytes > limits.aggregateAttachmentBytes) {
+        throw new Error(
+          `CoreMail attachments exceed ${limits.aggregateAttachmentBytes} aggregate bytes`,
+        );
+      }
+      await pushPart(
+        `attachment-${index}`,
+        'attachment',
+        attachment.contentType || 'application/octet-stream',
+        bytes,
+        attachment.filename,
+      );
+    }
+    if (parts.length === 0) {
+      throw new Error('Either text or html is required for service mail');
+    }
+    return parts;
+  }
+
+  private buildCoreMailDescriptor(
+    optionsArg: IServiceMailSendOptions,
+    credentialsArg: IServiceMailCoreMailCredentials,
+    partsArg: plugins.servezoneInterfaces.data.ICoreMailContentDescriptor[],
+  ): plugins.servezoneInterfaces.data.ICoreMailOutboundMessageDescriptor {
+    const limits = plugins.servezoneInterfaces.data.coreMailLimits;
+    const to = this.listToArray(optionsArg.to).map((addressArg) => this.toCoreMailMailbox(addressArg));
+    const cc = optionsArg.cc
+      ? this.listToArray(optionsArg.cc).map((addressArg) => this.toCoreMailMailbox(addressArg))
+      : undefined;
+    const bcc = optionsArg.bcc
+      ? this.listToArray(optionsArg.bcc).map((addressArg) => this.toCoreMailMailbox(addressArg))
+      : undefined;
+    const recipientCount = to.length + (cc?.length || 0) + (bcc?.length || 0);
+    if (to.length === 0) throw new Error('CoreMail requires at least one To recipient');
+    if (recipientCount > limits.recipientCount) {
+      throw new Error(`CoreMail accepts at most ${limits.recipientCount} recipients`);
+    }
+    // Ordered header list; CoreMail rejects transport-owned MIME headers itself.
+    const headers = optionsArg.headers
+      ? Object.entries(optionsArg.headers).map(([nameArg, valueArg]) => ({
+          name: nameArg,
+          value: String(valueArg),
+        }))
+      : undefined;
+    return {
+      sender: this.toCoreMailMailbox(credentialsArg.from),
+      recipients: { to, ...(cc ? { cc } : {}), ...(bcc ? { bcc } : {}) },
+      ...(optionsArg.replyTo !== undefined
+        ? { replyTo: this.toCoreMailMailbox(optionsArg.replyTo) }
+        : {}),
+      subject: optionsArg.subject,
+      ...(headers ? { headers } : {}),
+      parts: partsArg,
+    };
+  }
+
+  /** Re-throws a CoreMail failure on the app-facing error surface. */
+  private translateCoreMailError(errorArg: unknown): never {
+    const data = (errorArg as { data?: unknown })?.data as
+      | plugins.servezoneInterfaces.data.ICoreMailErrorData
+      | undefined;
+    const code = data?.code;
+    const message = (errorArg as Error)?.message || 'CoreMail rejected the submission';
+    if (code) {
+      const mapped = resolveSubmissionErrorCode(code);
+      if (mapped) throw new ServiceMailSubmissionError(mapped, message);
+      throw new Error(`CoreMail ${code}: ${message}`);
+    }
+    throw errorArg instanceof Error ? errorArg : new Error(message);
+  }
+
+  private async sendMailViaCoreMail(
+    optionsArg: IServiceMailSendOptions,
+    credentialsArg: IServiceMailCoreMailCredentials,
+  ): Promise<IServiceMailSendResult> {
+    const connector = this.getConfiguredCoreMailConnector(credentialsArg);
+    const parts = await this.buildCoreMailParts(optionsArg);
+    const descriptor = this.buildCoreMailDescriptor(
+      optionsArg,
+      credentialsArg,
+      parts.map((partArg) => partArg.descriptor),
+    );
+    try {
+      const prepared = await connector.prepareOutboundSubmission({
+        // CoreMail requires a replay key; IServiceMailSendOptions leaves it
+        // optional because the dcrouter path treats an omitted key as "no
+        // replay protection". A fresh random key per call reproduces exactly
+        // that semantic without weakening a key the caller did supply.
+        idempotencyKey: optionsArg.idempotencyKey || globalThis.crypto.randomUUID(),
+        message: descriptor,
+      });
+      let submission = prepared.submission;
+      if (!prepared.replayed) {
+        for (const part of parts) {
+          submission = await connector.uploadOutboundPart({
+            submissionId: submission.submissionId,
+            part: part.descriptor,
+            bytes: part.bytes,
+          });
+        }
+        submission = await connector.finalizeOutboundSubmission(submission.submissionId);
+      }
+      const recipients = [
+        ...this.listToArray(optionsArg.to),
+        ...(optionsArg.cc ? this.listToArray(optionsArg.cc) : []),
+        ...(optionsArg.bcc ? this.listToArray(optionsArg.bcc) : []),
+      ];
+      return {
+        messageId: submission.submissionId,
+        spoolItemId: submission.submissionId,
+        accepted: recipients,
+        rejected: [],
+        response: submission.state,
+      };
+    } catch (error) {
+      this.translateCoreMailError(error);
+    }
+  }
+
   public async getMailDeliveryStatus(
     spoolItemIdArg: string,
     addressArg?: string,
@@ -282,6 +625,17 @@ export class SzEmailConnector {
     if (!spoolItemId) {
       throw new Error('spoolItemId is required');
     }
+    const coreMailCredentials = await this.getCoreMailCredentials(addressArg);
+    if (coreMailCredentials) {
+      const connector = this.getConfiguredCoreMailConnector(coreMailCredentials);
+      let submission: plugins.servezoneInterfaces.data.ICoreMailSubmission;
+      try {
+        submission = await connector.getOutboundSubmission(spoolItemId);
+      } catch (error) {
+        this.translateCoreMailError(error);
+      }
+      return this.toMailDeliveryStatus(submission, coreMailCredentials);
+    }
     const credentials = await this.getServiceMailTypedCredentials(addressArg);
     const typedSocket = await this.getMailTypedSocket(credentials.typedUrl);
     const request = typedSocket.createTypedRequest<plugins.servezoneInterfaces.requests.mail.IReq_GetMailDeliveryStatus>('getMailDeliveryStatus');
@@ -294,24 +648,161 @@ export class SzEmailConnector {
     });
   }
 
+  /**
+   * Projects one CoreMail submission onto the dcrouter delivery-status shape.
+   * CoreMail keeps no per-attempt journal, so `attempts` carries at most one
+   * synthesized entry describing the current state, and `bounceEvents` stays
+   * empty; `spoolItem.attempts` is CoreMail's own attempt counter.
+   */
+  private toMailDeliveryStatus(
+    submissionArg: plugins.servezoneInterfaces.data.ICoreMailSubmission,
+    credentialsArg: IServiceMailCoreMailCredentials,
+  ): plugins.servezoneInterfaces.data.IMailDeliveryStatus {
+    const status = coreMailStateToSpoolStatus[submissionArg.state];
+    // CoreMail fronts dcrouter, which performs the actual MTA relay; there is
+    // no 'coremail' member in TMailDeliveryTargetType.
+    const target: plugins.servezoneInterfaces.data.IMailDeliveryTargetSummary = {
+      type: 'mtaRelay',
+      label: 'coremail',
+      url: credentialsArg.endpointUrl,
+    };
+    return {
+      spoolItem: {
+        id: submissionArg.submissionId,
+        direction: 'outbound',
+        status,
+        envelope: { mailFrom: credentialsArg.from, rcptTo: [] },
+        messageId: submissionArg.transportMessageId,
+        target,
+        attempts: submissionArg.attempts,
+        nextAttemptAt: submissionArg.nextAttemptAt,
+        lastError: submissionArg.error
+          ? `CoreMail ${submissionArg.error.code}`
+          : undefined,
+        createdAt: submissionArg.createdAt,
+        updatedAt: submissionArg.updatedAt,
+      },
+      attempts: submissionArg.attempts > 0
+        ? [{
+            id: `${submissionArg.submissionId}:${submissionArg.attempts}`,
+            spoolItemId: submissionArg.submissionId,
+            target,
+            status,
+            startedAt: submissionArg.acceptedAt || submissionArg.createdAt,
+            completedAt: submissionArg.deliveredAt || submissionArg.terminalAt,
+            response: submissionArg.error ? submissionArg.error.code : undefined,
+          }]
+        : [],
+      bounceEvents: [],
+    };
+  }
+
   public async registerInboundHandler(
     handlerArg: TServiceMailInboundHandler,
     addressArg?: string,
   ): Promise<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response']> {
     this.inboundHandler = handlerArg;
+    const coreMailCredentials = await this.getCoreMailCredentials(addressArg);
+    if (coreMailCredentials) {
+      const connector = this.getConfiguredCoreMailConnector(coreMailCredentials);
+      connector.startInboundPolling(async (fetchedArg) => {
+        const message = this.normalizeInboundMessage(
+          this.toInboundDeliveryPayload(fetchedArg),
+        );
+        const result = await handlerArg(message);
+        // A handler that declines must not acknowledge the delivery as processed.
+        if (result && result.accepted === false) {
+          throw new Error(result.message || 'Service mail inbound handler declined the delivery');
+        }
+      }, this.coreMailInboundPollOptions);
+      this.inboundEndpointRegistrations.add(coreMailCredentials.from);
+      return { success: true, addresses: [coreMailCredentials.from] };
+    }
     this.ensureInboundTypedHandler();
     const credentials = await this.getServiceMailTypedCredentials(addressArg);
     const typedSocket = await this.getMailTypedSocket(credentials.typedUrl);
     const result = await this.registerServiceMailEndpoint(typedSocket, credentials);
-    const registeredAddresses = result.addresses?.length ? result.addresses : [credentials.from];
-    for (const address of registeredAddresses) {
-      this.inboundEndpointRegistrations.add(address.trim().toLowerCase());
-    }
+    this.inboundEndpointRegistrations.add(credentials.from);
     return result;
   }
 
   public async stop(): Promise<void> {
+    // The mail socket this connector owns is released first; the CoreMail pull
+    // loop is released afterwards so stopping order stays observable to callers.
     await this.stopMailTypedSocket();
+    // The shared connector belongs to SzPlatformClient, so only its pull loop is
+    // released here; connectors this instance created are stopped outright.
+    await this.platformClientRef.coreMailConnector.stopInboundPolling();
+    const ownedConnectors = [...this.ownedCoreMailConnectors.values()];
+    this.ownedCoreMailConnectors.clear();
+    await Promise.allSettled(ownedConnectors.map((connectorArg) => connectorArg.stop()));
+    while (this.restorationOperations.size) await Promise.allSettled([...this.restorationOperations]);
+  }
+
+  /**
+   * Tunes the CoreMail pull loop before registerInboundHandler starts it.
+   * CoreMail never pushes, so cadence is a client-side choice.
+   */
+  public setCoreMailInboundPollOptions(
+    optionsArg: ISzCoreMailInboundPollOptions,
+  ): void {
+    this.coreMailInboundPollOptions = { ...optionsArg };
+  }
+
+  /**
+   * Projects one fetched CoreMail delivery onto the same payload shape dcrouter
+   * sends to deliverInboundMail, so both transports reach the app handler
+   * through normalizeInboundMessage unchanged.
+   */
+  private toInboundDeliveryPayload(
+    fetchedArg: ISzCoreMailInboundFetchResult,
+  ): plugins.servezoneInterfaces.data.IMailInboundMessagePayload {
+    const rawMessage = new TextDecoder().decode(fetchedArg.bytes);
+    return {
+      spoolItemId: fetchedArg.delivery.deliveryId,
+      envelope: {
+        mailFrom: fetchedArg.delivery.envelope.mailFrom,
+        rcptTo: fetchedArg.delivery.envelope.rcptTo,
+      },
+      rawMessage,
+      sizeBytes: fetchedArg.delivery.rawMime.lengthBytes,
+      messageId: fetchedArg.delivery.messageId,
+      subject: fetchedArg.delivery.subject,
+      headers: this.extractInboundHeaders(rawMessage),
+      receivedAt: fetchedArg.delivery.receivedAt,
+    };
+  }
+
+  /**
+   * RFC 5322 header-block extraction over the fetched MIME. Mirrors the
+   * projection dcrouter performs before deliverInboundMail so both transports
+   * hand the app the same `headers` record: unfold continuation lines, repeat
+   * names collapse into an array. Bodies are not parsed — the inbound contract
+   * carries `rawMessage`, not decoded text/html/attachments.
+   */
+  private extractInboundHeaders(rawMessageArg: string): Record<string, string | string[]> {
+    const headers: Record<string, string | string[]> = {};
+    const headerText = rawMessageArg.split(/\r?\n\r?\n/, 1)[0] || '';
+    let currentHeader = '';
+    for (const line of headerText.split(/\r?\n/)) {
+      if (/^[\t ]/.test(line) && currentHeader) {
+        const existing = headers[currentHeader];
+        const base = Array.isArray(existing) ? existing[existing.length - 1] : existing;
+        const folded = `${base || ''} ${line.trim()}`;
+        if (Array.isArray(existing)) existing[existing.length - 1] = folded;
+        else headers[currentHeader] = folded;
+        continue;
+      }
+      const separatorIndex = line.indexOf(':');
+      if (separatorIndex < 1) continue;
+      currentHeader = line.slice(0, separatorIndex).trim();
+      const value = line.slice(separatorIndex + 1).trim();
+      const existing = headers[currentHeader];
+      if (Array.isArray(existing)) existing.push(value);
+      else if (existing !== undefined) headers[currentHeader] = [String(existing), value];
+      else headers[currentHeader] = value;
+    }
+    return headers;
   }
 
   public normalizeInboundMessage(payloadArg: unknown): IServiceMailInboundMessage {
@@ -361,7 +852,7 @@ export class SzEmailConnector {
   private ensureInboundTypedHandler(): void {
     if (this.inboundTypedHandlerRegistered) return;
     this.inboundTypedHandlerRegistered = true;
-    this.platformClientRef.typedrouter.addTypedHandler(
+    this.mailRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_DeliverInboundMail>(
         'deliverInboundMail',
         async (dataArg) => {
@@ -378,6 +869,162 @@ export class SzEmailConnector {
 
   public async sendActionLink(optionsArg: { toArg: string; subject: string; text: string }) {}
 
+  /**
+   * Env names for one CoreMail binding. Unscoped names use the MAIL_COREMAIL_
+   * prefix; per-address names insert the same token readMailEnv uses.
+   */
+  private getCoreMailEnvNames(tokenArg?: string): Record<
+    'url' | 'bindingId' | 'credentialId' | 'credentialVersion' | 'credentialSecret',
+    string
+  > {
+    const prefix = tokenArg ? `MAIL_${tokenArg}_COREMAIL_` : 'MAIL_COREMAIL_';
+    return {
+      url: `${prefix}URL`,
+      bindingId: `${prefix}BINDING_ID`,
+      credentialId: `${prefix}CREDENTIAL_ID`,
+      credentialVersion: `${prefix}CREDENTIAL_VERSION`,
+      credentialSecret: `${prefix}CREDENTIAL_SECRET`,
+    };
+  }
+
+  private async readCoreMailEnv(tokenArg?: string): Promise<{
+    url?: string;
+    bindingId?: string;
+    credentialId?: string;
+    credentialVersion?: string;
+    credentialSecret?: string;
+  }> {
+    const names = this.getCoreMailEnvNames(tokenArg);
+    return {
+      url: await this.readMailEnvVar(names.url),
+      bindingId: await this.readMailEnvVar(names.bindingId),
+      credentialId: await this.readMailEnvVar(names.credentialId),
+      credentialVersion: await this.readMailEnvVar(names.credentialVersion),
+      credentialSecret: await this.readMailEnvVar(names.credentialSecret),
+    };
+  }
+
+  private listMissingCoreMailEnvNames(
+    envArg: { url?: string; bindingId?: string; credentialId?: string; credentialVersion?: string; credentialSecret?: string },
+    tokenArg?: string,
+  ): string[] {
+    const names = this.getCoreMailEnvNames(tokenArg);
+    const missing: string[] = [];
+    if (!envArg.url) missing.push(names.url);
+    if (!envArg.bindingId) missing.push(names.bindingId);
+    if (!envArg.credentialId) missing.push(names.credentialId);
+    if (!envArg.credentialVersion) missing.push(names.credentialVersion);
+    if (!envArg.credentialSecret) missing.push(names.credentialSecret);
+    return missing;
+  }
+
+  /**
+   * Resolves the CoreMail group for one address. Scoped values win wholesale,
+   * exactly like readMailEnv: if any MAIL_<TOKEN>_COREMAIL_* value is present
+   * the scoped group is used on its own and the unscoped group is not consulted.
+   * Returns undefined when no CoreMail value is configured at all; a partially
+   * configured group throws instead of silently falling back to dcrouter.
+   */
+  private async getCoreMailCredentials(
+    addressArg?: string,
+  ): Promise<IServiceMailCoreMailCredentials | undefined> {
+    const requestedAddress = addressArg?.trim().toLowerCase();
+    const requestedToken = requestedAddress ? this.getMailEnvToken(requestedAddress) : undefined;
+    const scopedCoreMail = requestedToken ? await this.readCoreMailEnv(requestedToken) : undefined;
+    const hasScopedCoreMail = Boolean(scopedCoreMail && Object.values(scopedCoreMail).some(Boolean));
+    const coreMailEnv = hasScopedCoreMail ? scopedCoreMail! : await this.readCoreMailEnv();
+    if (!Object.values(coreMailEnv).some(Boolean)) return undefined;
+
+    const token = hasScopedCoreMail ? requestedToken : undefined;
+    const missing = this.listMissingCoreMailEnvNames(coreMailEnv, token);
+    if (missing.length > 0) {
+      throw new Error(`CoreMail service mail is partially configured. Missing: ${missing.join(', ')}`);
+    }
+
+    // The From address follows the same scoped-wins rule as the typed path.
+    const addressEnv = hasScopedCoreMail ? await this.readMailEnv(requestedToken) : undefined;
+    const env = addressEnv && Object.values(addressEnv).some(Boolean)
+      ? addressEnv
+      : await this.readMailEnv();
+    const from = env.from?.trim().toLowerCase();
+    if (!from) {
+      throw new Error(
+        `${token ? `MAIL_${token}_FROM` : 'MAIL_FROM'} is required for CoreMail service mail`,
+      );
+    }
+    if (requestedAddress && from !== requestedAddress) {
+      throw new Error(`No CoreMail service mail credentials are configured for ${requestedAddress}`);
+    }
+    const credentialVersion = Number(coreMailEnv.credentialVersion);
+    if (!Number.isSafeInteger(credentialVersion) || credentialVersion < 1) {
+      throw new Error(
+        `${this.getCoreMailEnvNames(token).credentialVersion} must be a positive integer`,
+      );
+    }
+    return {
+      from,
+      endpointUrl: coreMailEnv.url!,
+      bindingId: coreMailEnv.bindingId!,
+      credentialId: coreMailEnv.credentialId!,
+      credentialVersion,
+      credentialSecret: coreMailEnv.credentialSecret!,
+      addressToken: token,
+    };
+  }
+
+  /** Value-free key identifying one CoreMail binding; never includes the secret. */
+  private getCoreMailConnectorKey(
+    bindingArg: {
+      endpointUrl: string;
+      bindingId: string;
+      credentialId: string;
+      credentialVersion: number;
+    },
+  ): string {
+    return JSON.stringify([
+      bindingArg.endpointUrl,
+      bindingArg.bindingId,
+      bindingArg.credentialId,
+      bindingArg.credentialVersion,
+    ]);
+  }
+
+  /**
+   * Returns the connector that serves this address's binding.
+   *
+   * SzCoreMailConnector.configure() is one-shot, and a service may hold several
+   * bindings at once (an unscoped MAIL_COREMAIL_* group plus per-address
+   * MAIL_<TOKEN>_COREMAIL_* groups). One shared instance therefore cannot serve
+   * them all: the client's shared connector is reused only while it is still
+   * unconfigured or already configured for this exact binding, and every other
+   * binding gets a dedicated instance owned and stopped by this email connector.
+   */
+  private getConfiguredCoreMailConnector(
+    credentialsArg: IServiceMailCoreMailCredentials,
+  ): SzCoreMailConnector {
+    const options = {
+      endpointUrl: credentialsArg.endpointUrl,
+      bindingId: credentialsArg.bindingId,
+      credentialId: credentialsArg.credentialId,
+      credentialVersion: credentialsArg.credentialVersion,
+      credentialSecret: credentialsArg.credentialSecret,
+    };
+    const requestedKey = this.getCoreMailConnectorKey(options);
+    const shared = this.platformClientRef.coreMailConnector;
+    const sharedBinding = shared.configuredBinding;
+    if (!sharedBinding || this.getCoreMailConnectorKey(sharedBinding) === requestedKey) {
+      // Unconfigured: adopt it. Already this binding: configure() is a no-op.
+      shared.configure(options);
+      return shared;
+    }
+    const owned = this.ownedCoreMailConnectors.get(requestedKey);
+    if (owned) return owned;
+    const connector = new SzCoreMailConnector();
+    connector.configure(options);
+    this.ownedCoreMailConnectors.set(requestedKey, connector);
+    return connector;
+  }
+
   private async readMailEnv(tokenArg?: string): Promise<{
     from?: string;
     smtpHost?: string;
@@ -445,6 +1092,7 @@ export class SzEmailConnector {
   }
 
   private async getMailTypedSocket(urlArg: string): Promise<plugins.typedsocket.TypedSocket> {
+    this.platformClientRef.assertRunning();
     const normalizedUrl = this.normalizeTypedSocketUrl(urlArg);
     if (this.mailTypedSocket && this.mailTypedSocketUrl === normalizedUrl) {
       return this.mailTypedSocket;
@@ -455,20 +1103,27 @@ export class SzEmailConnector {
     if (this.mailTypedSocket || this.mailTypedSocketPromise) {
       await this.stopMailTypedSocket();
     }
+    this.platformClientRef.assertRunning();
     this.mailTypedSocketUrl = normalizedUrl;
     const abortController = new AbortController();
     this.mailTypedSocketAbortController = abortController;
     const socketPromise = plugins.typedsocket.TypedSocket.createClient(
-      this.platformClientRef.typedrouter,
+      this.mailRouter,
       normalizedUrl,
-      { autoReconnect: true, abortSignal: abortController.signal },
+      { autoReconnect: true, abortSignal: abortController.signal,
+        restoreConnection: (context) => {
+          const operation = this.restoreMailConnection(context, normalizedUrl, abortController.signal);
+          this.restorationOperations.add(operation);
+          void operation.then(() => this.restorationOperations.delete(operation), () => this.restorationOperations.delete(operation));
+          return operation;
+        },
+      },
     );
     this.mailTypedSocketPromise = socketPromise;
     try {
       const socket = await socketPromise;
       if (this.mailTypedSocketPromise === socketPromise && this.mailTypedSocketUrl === normalizedUrl) {
         this.mailTypedSocket = socket;
-        this.watchMailTypedSocketStatus(socket);
       } else {
         await socket.stop();
       }
@@ -487,148 +1142,49 @@ export class SzEmailConnector {
     const socket = this.mailTypedSocket;
     const socketPromise = this.mailTypedSocketPromise;
     const abortController = this.mailTypedSocketAbortController;
-    const statusSubscription = this.mailTypedSocketStatusSubscription;
     this.mailTypedSocket = undefined;
     this.mailTypedSocketPromise = undefined;
     this.mailTypedSocketUrl = undefined;
     this.mailTypedSocketAbortController = undefined;
-    this.mailTypedSocketStatusSubscription = undefined;
-    statusSubscription?.unsubscribe();
     abortController?.abort();
     if (socket) {
       await socket.stop();
       return;
     }
     if (socketPromise) {
-      try {
-        const pendingSocket = await socketPromise;
-        await pendingSocket.stop();
-      } catch {
-        // The pending connection already failed; there is no socket to stop.
-      }
+      const pendingSocket = await socketPromise.catch(() => undefined);
+      await pendingSocket?.stop();
     }
   }
 
-  private watchMailTypedSocketStatus(socketArg: plugins.typedsocket.TypedSocket): void {
-    this.mailTypedSocketStatusSubscription?.unsubscribe();
-    this.mailTypedSocketStatusSubscription = socketArg.statusSubject.subscribe((statusArg) => {
-      void this.handleMailTypedSocketStatus(socketArg, statusArg);
-    });
-  }
-
-  private async handleMailTypedSocketStatus(
-    socketArg: plugins.typedsocket.TypedSocket,
-    statusArg: plugins.typedsocket.TConnectionStatus,
+  private async restoreMailConnection(
+    context: plugins.typedsocket.ITypedSocketConnectionRestoreContext,
+    url: string, signal: AbortSignal,
   ): Promise<void> {
-    if (statusArg !== 'connected' || this.mailTypedSocket !== socketArg) {
-      return;
-    }
-    try {
-      await this.replayInboundEndpointRegistrationsWithRetry(socketArg);
-    } catch (error) {
-      console.warn('Could not re-register service mail endpoint after reconnect:', (error as Error).message);
-    }
-  }
-
-  private async replayInboundEndpointRegistrationsWithRetry(
-    socketArg: plugins.typedsocket.TypedSocket,
-  ): Promise<void> {
-    if (!this.inboundEndpointRegistrations.size) {
-      return;
-    }
-    if (this.inboundEndpointReplayPromise) {
-      return await this.inboundEndpointReplayPromise;
-    }
-
-    const replayPromise = this.replayInboundEndpointRegistrationsWithRetryInner(socketArg);
-    this.inboundEndpointReplayPromise = replayPromise;
-    try {
-      await replayPromise;
-    } finally {
-      if (this.inboundEndpointReplayPromise === replayPromise) {
-        this.inboundEndpointReplayPromise = undefined;
-      }
-    }
-  }
-
-  private async replayInboundEndpointRegistrationsWithRetryInner(
-    socketArg: plugins.typedsocket.TypedSocket,
-  ): Promise<void> {
-    let lastError: unknown;
-    const delays = [0, ...this.inboundEndpointReplayRetryDelaysMs];
-    for (let attemptIndex = 0; attemptIndex < delays.length; attemptIndex++) {
-      if (this.mailTypedSocket !== socketArg) {
-        return;
-      }
-      if (attemptIndex > 0) {
-        const shouldContinue = await this.waitForInboundEndpointReplayRetry(socketArg, delays[attemptIndex]);
-        if (!shouldContinue) {
-          return;
-        }
-      }
-      try {
-        await this.replayInboundEndpointRegistrationsOnce(socketArg);
-        return;
-      } catch (error) {
-        lastError = error;
-      }
-    }
-    throw lastError instanceof Error
-      ? lastError
-      : new Error('Could not re-register service mail endpoint after reconnect');
-  }
-
-  private async replayInboundEndpointRegistrationsOnce(
-    socketArg: plugins.typedsocket.TypedSocket,
-  ): Promise<void> {
-    for (const address of this.inboundEndpointRegistrations.values()) {
-      if (this.mailTypedSocket !== socketArg) {
-        return;
-      }
+    for (const address of this.inboundEndpointRegistrations) {
+      signal.throwIfAborted(); context.abortSignal.throwIfAborted();
       const credentials = await this.getServiceMailTypedCredentials(address);
-      if (this.normalizeTypedSocketUrl(credentials.typedUrl) !== this.mailTypedSocketUrl) {
-        continue;
-      }
-      await this.registerServiceMailEndpoint(socketArg, credentials);
+      if (credentials.typedUrl !== url) continue;
+      await this.registerServiceMailEndpoint({ createTypedRequest: context.createTypedRequest }, credentials, context.abortSignal);
+      signal.throwIfAborted(); context.abortSignal.throwIfAborted();
     }
   }
 
-  private async waitForInboundEndpointReplayRetry(
-    socketArg: plugins.typedsocket.TypedSocket,
-    delayMsArg: number,
-  ): Promise<boolean> {
-    if (this.mailTypedSocket !== socketArg) {
-      return false;
-    }
-    const abortSignal = this.mailTypedSocketAbortController?.signal;
-    if (abortSignal?.aborted) {
-      return false;
-    }
-    return await new Promise<boolean>((resolve) => {
-      const resolveOnce = (resultArg: boolean) => {
-        clearTimeout(timeout);
-        abortSignal?.removeEventListener('abort', abortHandler);
-        resolve(resultArg && this.mailTypedSocket === socketArg);
-      };
-      const abortHandler = () => resolveOnce(false);
-      const timeout = setTimeout(() => resolveOnce(true), delayMsArg);
-      abortSignal?.addEventListener('abort', abortHandler, { once: true });
-    });
-  }
-
   private async registerServiceMailEndpoint(
-    typedSocketArg: plugins.typedsocket.TypedSocket,
+    typedSocketArg: Pick<plugins.typedsocket.TypedSocket, 'createTypedRequest'>,
     credentialsArg: IServiceMailTypedCredentials,
+    abortSignal?: AbortSignal,
   ): Promise<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response']> {
     const request = typedSocketArg.createTypedRequest<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint>('registerServiceMailEndpoint');
+    request.skipHooks = true;
     const result = await request.fire({
       auth: {
         credentialId: credentialsArg.credentialId,
         credentialSecret: credentialsArg.credentialSecret,
       },
       addresses: [credentialsArg.from],
-    });
-    if (!result.success) {
+    }, { maxRetries: 0, abortSignal });
+    if (!result.success || result.addresses?.length !== 1 || result.addresses[0] !== credentialsArg.from) {
       throw new Error(result.message || 'Could not register service mail endpoint');
     }
     return result;