@lenne.tech/nest-server 11.43.5 → 11.43.6

package/migration-guides/11.43.5-to-11.43.6.md

@@ -0,0 +1,53 @@
+# Migration Guide: 11.43.5 → 11.43.6
+
+## Overview
+
+| Category             | Details                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------- |
+| **New Features**     | Optional Reply-To for outgoing mail: `email.defaultReplyTo` and a per-call `replyTo` (§1)               |
+| **Breaking Changes** | None                                                                                                    |
+| **Migration Effort** | None. Set `email.defaultReplyTo` only if answers to your mail should go to another address (§1)         |
+
+## Quick Migration
+
+```bash
+pnpm add @lenne.tech/nest-server@11.43.6
+pnpm run update   # nest-server-starter based projects
+```
+
+Vendor-mode projects update the core to the tag `11.43.6`: `/lt-dev:backend:update-nest-server-core --target 11.43.6`.
+Without `--target` the updater syncs to the latest tag, which is on the 12.x line.
+
+## 1. Reply-To for outgoing mail
+
+`EmailService.sendMail()` can set a `Reply-To` header, so a recipient's answer goes to another address than the
+sender, e.g. a shared support mailbox while mail goes out from `noreply@…`. Nothing changes until you set it.
+
+```typescript
+// config.env.ts
+email: {
+  defaultSender: { email: 'noreply@example.com', name: 'Example' },
+  defaultReplyTo: 'support@example.com', // or '"Example Support" <support@example.com>'
+},
+```
+
+As an environment variable:
+
+```bash
+NSC__EMAIL__DEFAULT_REPLY_TO=support@example.com
+```
+
+A call can override it, or send one mail without it:
+
+```typescript
+await this.emailService.sendMail(to, subject, { replyTo: 'sales@example.com', htmlTemplate, templateData });
+await this.emailService.sendMail(to, subject, { replyTo: false, htmlTemplate, templateData });
+```
+
+The default applies to every mail the service sends over SMTP, Better-Auth's verification and password-reset mail
+included. Mail sent through Brevo (`brevo.apiKey`) or Mailjet is not affected: their templates carry their own
+reply-to. A value that is not a string is ignored with one warning rather than stopping the mail.
+
+## Module Documentation
+
+- Configuration reference: `email.defaultReplyTo` in `FRAMEWORK-API.md` (`IServerOptions.email`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.43.5",
+  "version": "11.43.6",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/interfaces/server-options.interface.ts

@@ -2510,6 +2510,17 @@ export interface IServerOptions {
    * SMTP and template configuration for sending emails
    */
   email?: {
+    /**
+     * Default Reply-To of every mail `EmailService.sendMail()` sends (11.43.6+): where a recipient's answer goes when it
+     * should not reach the sender address, e.g. a shared support mailbox. An address, or `"Name" <address>`.
+     *
+     * Absent (the default) → no Reply-To header, exactly as before. A call overrides it with `replyTo`, and
+     * `replyTo: false` sends that one mail without it. Set it through `NSC__EMAIL__DEFAULT_REPLY_TO`. Applies to the
+     * SMTP path (nodemailer, `email.smtp`): Brevo and Mailjet templates carry their own reply-to.
+     * @default undefined
+     */
+    defaultReplyTo?: string;
+
     /**
      * Data for default sender
      */

package/src/core/common/services/email.service.ts

@@ -28,6 +28,9 @@ export class EmailService implements OnModuleDestroy {
   /** Once-per-process latch for the SMTP TLS warning — a per-send warning would be noise. */
   private smtpTlsWarningEmitted = false;
 
+  /** Once-per-process latch for a Reply-To that is not a string. */
+  private replyToWarningEmitted = false;
+
   /**
    * Inject services
    */
@@ -76,6 +79,31 @@ export class EmailService implements OnModuleDestroy {
     );
   }
 
+  /**
+   * The Reply-To of one mail (11.43.6+): the call's `replyTo`, else `email.defaultReplyTo`, else none. `false` (or an
+   * empty string) sends this mail without one. A value that is not a string is dropped with a warning instead of
+   * failing the mail: a misconfigured default must not stop password-reset or verification mail.
+   */
+  protected resolveReplyTo(replyTo: false | string | undefined): string | undefined {
+    if (replyTo === false) {
+      return undefined;
+    }
+    const value: unknown = replyTo ?? this.configService.getFastButReadOnly('email.defaultReplyTo');
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    if (typeof value === 'string') {
+      return value.trim() || undefined;
+    }
+    if (!this.replyToWarningEmitted) {
+      this.replyToWarningEmitted = true;
+      this.emailServiceLogger.warn(
+        `Reply-To ignored: expected an address string (email.defaultReplyTo / replyTo), got ${typeof value}.`,
+      );
+    }
+    return undefined;
+  }
+
   onModuleDestroy(): void {
     if (this.cachedTransporter) {
       this.cachedTransporter.close();
@@ -94,6 +122,8 @@ export class EmailService implements OnModuleDestroy {
       attachments?: Attachment[];
       html?: string;
       htmlTemplate?: string;
+      /** Reply-To of this mail; overrides `email.defaultReplyTo`, `false` sends it without one (11.43.6+) */
+      replyTo?: false | string;
       senderEmail?: string;
       senderName?: string;
       smtp?: MailTransportOptions;
@@ -189,11 +219,13 @@ export class EmailService implements OnModuleDestroy {
       this.cachedSmtpConfig = smtpKey;
     }
 
-    // Send mail
+    // Send mail; without a Reply-To the header is left out entirely
+    const replyTo = this.resolveReplyTo(config.replyTo);
     return this.cachedTransporter.sendMail({
       attachments,
       from: `"${senderName}" <${senderEmail}>`,
       html,
+      ...(replyTo ? { replyTo } : {}),
       subject,
       text,
       to: recipients,