@serve.zone/platformclient 4.0.0 → 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;
@@ -111,6 +206,13 @@ export class SzEmailConnector {
   private inboundHandler?: TServiceMailInboundHandler;
   private inboundTypedHandlerRegistered = false;
   private inboundEndpointRegistrations = new Set<string>();
+  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;
@@ -168,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,
@@ -230,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');
@@ -273,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,
@@ -281,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');
@@ -293,11 +648,76 @@ 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);
@@ -307,10 +727,84 @@ export class SzEmailConnector {
   }
 
   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 {
     const payload = this.asRecord(payloadArg);
     const deliveryCandidate = this.asRecord(payload.delivery || payload.message || payload);
@@ -375,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;