fix: Support mailbox format for SMTP_FROM_EMAIL and SMTP_REPLY_EMAIL (outline#11784)

* Initial plan

* fix: Handle SMTP_FROM_EMAIL/SMTP_REPLY_EMAIL in mailbox format

Co-authored-by: tommoor <380914+tommoor@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tommoor <380914+tommoor@users.noreply.github.com>

Author: Copilot

server/emails/templates/BaseEmail.tsx

@@ -201,6 +201,10 @@ export default abstract class BaseEmail<
     );
 
     const parsedFrom = addressparser(env.SMTP_FROM_EMAIL)[0];
+    invariant(
+      parsedFrom?.address?.includes("@"),
+      `SMTP_FROM_EMAIL is not a valid email address: "${env.SMTP_FROM_EMAIL}"`
+    );
     const domain = parsedFrom.address.split("@")[1];
     const customFromName = this.fromName?.(props);
 

server/env.ts

@@ -12,7 +12,6 @@ import {
   Length,
   IsNumber,
   IsIn,
-  IsEmail,
   IsBoolean,
 } from "class-validator";
 import uniq from "lodash/uniq";
@@ -24,6 +23,7 @@ import {
   CannotUseWithAny,
   IsInCaseInsensitive,
   IsDatabaseUrl,
+  IsMailboxAddress,
 } from "@server/utils/validators";
 import Deprecated from "./models/decorators/Deprecated";
 import { getArg } from "./utils/args";
@@ -405,15 +405,15 @@ export class Environment {
   /**
    * The email address from which emails are sent.
    */
-  @IsEmail({ allow_display_name: true, allow_ip_domain: true })
+  @IsMailboxAddress()
   @IsOptional()
   public SMTP_FROM_EMAIL = this.toOptionalString(environment.SMTP_FROM_EMAIL);
 
   /**
    * The reply-to address for emails sent from Outline. If unset the from
    * address is used by default.
    */
-  @IsEmail({ allow_display_name: true, allow_ip_domain: true })
+  @IsMailboxAddress()
   @IsOptional()
   public SMTP_REPLY_EMAIL = this.toOptionalString(environment.SMTP_REPLY_EMAIL);
 

server/utils/validators.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "@jest/globals";
-import { isDatabaseUrl } from "./validators";
+import { isDatabaseUrl, isMailboxAddress } from "./validators";
 
 describe("isDatabaseUrl", () => {
   const defaultOptions = {
@@ -249,3 +249,70 @@ describe("isDatabaseUrl", () => {
     });
   });
 });
+
+describe("isMailboxAddress", () => {
+  describe("plain email addresses", () => {
+    it("should accept a plain email address", () => {
+      expect(isMailboxAddress("user@example.com")).toBe(true);
+    });
+
+    it("should accept an email with IP domain", () => {
+      expect(isMailboxAddress("user@192.168.1.1")).toBe(true);
+    });
+
+    it("should reject an invalid email address", () => {
+      expect(isMailboxAddress("notanemail")).toBe(false);
+    });
+
+    it("should reject an email without domain", () => {
+      expect(isMailboxAddress("user@")).toBe(false);
+    });
+  });
+
+  describe("mailbox format addresses", () => {
+    it("should accept a simple mailbox format", () => {
+      expect(isMailboxAddress("Outline <user@example.com>")).toBe(true);
+    });
+
+    it("should accept a mailbox format with a period in the display name", () => {
+      expect(isMailboxAddress("My App v1.0 <user@example.com>")).toBe(true);
+    });
+
+    it("should accept a mailbox format with quoted display name containing a comma", () => {
+      expect(
+        isMailboxAddress('"Company, Inc." <user@example.com>')
+      ).toBe(true);
+    });
+
+    it("should accept a mailbox format with a quoted display name", () => {
+      expect(isMailboxAddress('"Outline" <user@example.com>')).toBe(true);
+    });
+
+    it("should reject a mailbox format with an unquoted comma in the display name", () => {
+      // addressparser splits on commas, so this creates two addresses
+      expect(isMailboxAddress("Company, Inc. <user@example.com>")).toBe(false);
+    });
+
+    it("should reject a mailbox format with an empty email address", () => {
+      expect(isMailboxAddress("Outline <>")).toBe(false);
+    });
+
+    it("should reject a mailbox format with an invalid email address", () => {
+      expect(isMailboxAddress("Outline <notanemail>")).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should reject an empty string", () => {
+      expect(isMailboxAddress("")).toBe(false);
+    });
+
+    it("should reject a string with only spaces", () => {
+      expect(isMailboxAddress("   ")).toBe(false);
+    });
+
+    it("should reject a group address", () => {
+      expect(isMailboxAddress("Group: user@example.com;")).toBe(false);
+    });
+  });
+});

server/utils/validators.ts

@@ -1,5 +1,7 @@
+import addressparser from "addressparser";
 import type { ValidationArguments, ValidationOptions } from "class-validator";
 import { registerDecorator } from "class-validator";
+import { isEmail } from "validator";
 
 /**
  * Validates a PostgreSQL database connection URL, including support for
@@ -264,3 +266,71 @@ export function IsDatabaseUrl(
     });
   };
 }
+
+/**
+ * Validates an email address in either plain format (email@domain.com) or
+ * mailbox format (Display Name <email@domain.com>). Uses addressparser to
+ * extract the email address before validation, which provides correct handling
+ * of display names that may contain characters like periods or other special
+ * characters.
+ *
+ * @param value the email address string to validate.
+ * @returns true if the value is a valid email or valid mailbox address, false otherwise.
+ */
+export function isMailboxAddress(value: string): boolean {
+  try {
+    const parsed = addressparser(value);
+    // If parsing results in multiple addresses (e.g., comma in unquoted display
+    // name), the input is malformed and should be rejected.
+    if (parsed.length !== 1) {
+      return false;
+    }
+    const [{ address }] = parsed;
+    if (!address?.includes("@")) {
+      return false;
+    }
+    return isEmail(address, { allow_ip_domain: true });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decorator that validates an email address in either plain format
+ * (email@domain.com) or mailbox format (Display Name <email@domain.com>).
+ *
+ * Unlike @IsEmail, this decorator supports display names containing characters
+ * such as periods, which are commonly used in application names
+ * (e.g., "App v1.0 <noreply@example.com>").
+ *
+ * Note: Display names containing commas must be quoted, e.g.:
+ * "Company, Inc." <email@example.com>
+ *
+ * @param validationOptions additional validation options.
+ * @returns decorator function.
+ */
+export function IsMailboxAddress(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      name: "isMailboxAddress",
+      target: object.constructor,
+      propertyName,
+      constraints: [],
+      options: validationOptions,
+      validator: {
+        validate(value: unknown) {
+          if (value === undefined || value === null) {
+            return true;
+          }
+          if (typeof value !== "string") {
+            return false;
+          }
+          return isMailboxAddress(value);
+        },
+        defaultMessage() {
+          return `${propertyName} must be a valid email address or use mailbox format (e.g., "Display Name <email@example.com>"). Note: display names containing commas must be quoted (e.g., '"Company, Inc." <email@example.com>').`;
+        },
+      },
+    });
+  };
+}