📡 feat: Support Unauthenticated SMTP Relays (#12322)

* allow smtp server that does not have authentication

* fix: align checkEmailConfig with optional SMTP credentials and add tests

Remove EMAIL_USERNAME/EMAIL_PASSWORD requirements from the hasSMTPConfig
predicate in checkEmailConfig() so the rest of the codebase (login,
startup checks, invite-user) correctly recognizes unauthenticated SMTP
as a valid email configuration.

Add a warning when only one of the two credential env vars is set,
in both sendEmail.js and checkEmailConfig(), to catch partial
misconfigurations early.

Add test coverage for both the transporter auth assembly in sendEmail.js
and the checkEmailConfig predicate in packages/api.

Document in .env.example that credentials are optional for
unauthenticated SMTP relays.

---------

Co-authored-by: Danny Avila <danny@librechat.ai>

.env.example

@@ -625,6 +625,7 @@ EMAIL_PORT=25
 EMAIL_ENCRYPTION=
 EMAIL_ENCRYPTION_HOSTNAME=
 EMAIL_ALLOW_SELFSIGNED=
+# Leave both empty for SMTP servers that do not require authentication
 EMAIL_USERNAME=
 EMAIL_PASSWORD=
 EMAIL_FROM_NAME=

api/server/utils/__tests__/sendEmail.spec.js

@@ -0,0 +1,143 @@
+const nodemailer = require('nodemailer');
+const { readFileAsString } = require('@librechat/api');
+
+jest.mock('nodemailer');
+jest.mock('@librechat/data-schemas', () => ({
+  logger: { debug: jest.fn(), warn: jest.fn(), error: jest.fn() },
+}));
+jest.mock('@librechat/api', () => ({
+  logAxiosError: jest.fn(),
+  isEnabled: jest.fn((val) => val === 'true' || val === true),
+  readFileAsString: jest.fn(),
+}));
+
+const savedEnv = { ...process.env };
+
+const mockSendMail = jest.fn().mockResolvedValue({ messageId: 'test-id' });
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...savedEnv };
+  process.env.EMAIL_HOST = 'smtp.example.com';
+  process.env.EMAIL_PORT = '587';
+  process.env.EMAIL_FROM = 'noreply@example.com';
+  process.env.APP_TITLE = 'TestApp';
+  delete process.env.EMAIL_USERNAME;
+  delete process.env.EMAIL_PASSWORD;
+  delete process.env.MAILGUN_API_KEY;
+  delete process.env.MAILGUN_DOMAIN;
+  delete process.env.EMAIL_SERVICE;
+  delete process.env.EMAIL_ENCRYPTION;
+  delete process.env.EMAIL_ENCRYPTION_HOSTNAME;
+  delete process.env.EMAIL_ALLOW_SELFSIGNED;
+
+  readFileAsString.mockResolvedValue({ content: '<p>{{name}}</p>' });
+  nodemailer.createTransport.mockReturnValue({ sendMail: mockSendMail });
+});
+
+afterAll(() => {
+  process.env = savedEnv;
+});
+
+/** Loads a fresh copy of sendEmail so process.env reads are re-evaluated. */
+function loadSendEmail() {
+  jest.resetModules();
+  jest.mock('nodemailer', () => ({
+    createTransport: jest.fn().mockReturnValue({ sendMail: mockSendMail }),
+  }));
+  jest.mock('@librechat/data-schemas', () => ({
+    logger: { debug: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  }));
+  jest.mock('@librechat/api', () => ({
+    logAxiosError: jest.fn(),
+    isEnabled: jest.fn((val) => val === 'true' || val === true),
+    readFileAsString: jest.fn().mockResolvedValue({ content: '<p>{{name}}</p>' }),
+  }));
+  return require('../sendEmail');
+}
+
+const baseParams = {
+  email: 'user@example.com',
+  subject: 'Test',
+  payload: { name: 'User' },
+  template: 'test.handlebars',
+};
+
+describe('sendEmail SMTP auth assembly', () => {
+  it('includes auth when both EMAIL_USERNAME and EMAIL_PASSWORD are set', async () => {
+    process.env.EMAIL_USERNAME = 'smtp_user';
+    process.env.EMAIL_PASSWORD = 'smtp_pass';
+    const sendEmail = loadSendEmail();
+    const { createTransport } = require('nodemailer');
+
+    await sendEmail(baseParams);
+
+    expect(createTransport).toHaveBeenCalledTimes(1);
+    const transporterOptions = createTransport.mock.calls[0][0];
+    expect(transporterOptions.auth).toEqual({
+      user: 'smtp_user',
+      pass: 'smtp_pass',
+    });
+  });
+
+  it('omits auth when both EMAIL_USERNAME and EMAIL_PASSWORD are absent', async () => {
+    const sendEmail = loadSendEmail();
+    const { createTransport } = require('nodemailer');
+
+    await sendEmail(baseParams);
+
+    expect(createTransport).toHaveBeenCalledTimes(1);
+    const transporterOptions = createTransport.mock.calls[0][0];
+    expect(transporterOptions.auth).toBeUndefined();
+  });
+
+  it('omits auth and logs a warning when only EMAIL_USERNAME is set', async () => {
+    process.env.EMAIL_USERNAME = 'smtp_user';
+    const sendEmail = loadSendEmail();
+    const { createTransport } = require('nodemailer');
+    const { logger: freshLogger } = require('@librechat/data-schemas');
+
+    await sendEmail(baseParams);
+
+    const transporterOptions = createTransport.mock.calls[0][0];
+    expect(transporterOptions.auth).toBeUndefined();
+    expect(freshLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('EMAIL_USERNAME and EMAIL_PASSWORD must both be set'),
+    );
+  });
+
+  it('omits auth and logs a warning when only EMAIL_PASSWORD is set', async () => {
+    process.env.EMAIL_PASSWORD = 'smtp_pass';
+    const sendEmail = loadSendEmail();
+    const { createTransport } = require('nodemailer');
+    const { logger: freshLogger } = require('@librechat/data-schemas');
+
+    await sendEmail(baseParams);
+
+    const transporterOptions = createTransport.mock.calls[0][0];
+    expect(transporterOptions.auth).toBeUndefined();
+    expect(freshLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('EMAIL_USERNAME and EMAIL_PASSWORD must both be set'),
+    );
+  });
+
+  it('does not log a warning when both credentials are properly set', async () => {
+    process.env.EMAIL_USERNAME = 'smtp_user';
+    process.env.EMAIL_PASSWORD = 'smtp_pass';
+    const sendEmail = loadSendEmail();
+    const { logger: freshLogger } = require('@librechat/data-schemas');
+
+    await sendEmail(baseParams);
+
+    expect(freshLogger.warn).not.toHaveBeenCalled();
+  });
+
+  it('does not log a warning when both credentials are absent', async () => {
+    const sendEmail = loadSendEmail();
+    const { logger: freshLogger } = require('@librechat/data-schemas');
+
+    await sendEmail(baseParams);
+
+    expect(freshLogger.warn).not.toHaveBeenCalled();
+  });
+});

api/server/utils/sendEmail.js

@@ -124,11 +124,20 @@ const sendEmail = async ({ email, subject, payload, template, throwError = true
         // Whether to accept unsigned certificates
         rejectUnauthorized: !isEnabled(process.env.EMAIL_ALLOW_SELFSIGNED),
       },
-      auth: {
+    };
+
+    const hasUsername = !!process.env.EMAIL_USERNAME;
+    const hasPassword = !!process.env.EMAIL_PASSWORD;
+    if (hasUsername && hasPassword) {
+      transporterOptions.auth = {
         user: process.env.EMAIL_USERNAME,
         pass: process.env.EMAIL_PASSWORD,
-      },
-    };
+      };
+    } else if (hasUsername !== hasPassword) {
+      logger.warn(
+        '[sendEmail] EMAIL_USERNAME and EMAIL_PASSWORD must both be set for authenticated SMTP, or both omitted for unauthenticated SMTP. Proceeding without authentication.',
+      );
+    }
 
     if (process.env.EMAIL_ENCRYPTION_HOSTNAME) {
       // Check the certificate against this name explicitly

packages/api/src/utils/__tests__/email.test.ts

@@ -0,0 +1,120 @@
+import { logger } from '@librechat/data-schemas';
+import { checkEmailConfig } from '../email';
+
+jest.mock('@librechat/data-schemas', () => ({
+  logger: { warn: jest.fn() },
+}));
+
+const savedEnv = { ...process.env };
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...savedEnv };
+  delete process.env.EMAIL_SERVICE;
+  delete process.env.EMAIL_HOST;
+  delete process.env.EMAIL_USERNAME;
+  delete process.env.EMAIL_PASSWORD;
+  delete process.env.EMAIL_FROM;
+  delete process.env.MAILGUN_API_KEY;
+  delete process.env.MAILGUN_DOMAIN;
+});
+
+afterAll(() => {
+  process.env = savedEnv;
+});
+
+describe('checkEmailConfig', () => {
+  describe('SMTP configuration', () => {
+    it('returns true with EMAIL_HOST and EMAIL_FROM (no credentials)', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      expect(checkEmailConfig()).toBe(true);
+    });
+
+    it('returns true with EMAIL_SERVICE and EMAIL_FROM (no credentials)', () => {
+      process.env.EMAIL_SERVICE = 'gmail';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      expect(checkEmailConfig()).toBe(true);
+    });
+
+    it('returns true with EMAIL_HOST, EMAIL_FROM, and full credentials', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      process.env.EMAIL_USERNAME = 'user';
+      process.env.EMAIL_PASSWORD = 'pass';
+      expect(checkEmailConfig()).toBe(true);
+    });
+
+    it('returns false when EMAIL_FROM is missing', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      expect(checkEmailConfig()).toBe(false);
+    });
+
+    it('returns false when neither EMAIL_HOST nor EMAIL_SERVICE is set', () => {
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      expect(checkEmailConfig()).toBe(false);
+    });
+
+    it('returns false when no email env vars are set', () => {
+      expect(checkEmailConfig()).toBe(false);
+    });
+  });
+
+  describe('partial credential warning', () => {
+    it('logs a warning when only EMAIL_USERNAME is set', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      process.env.EMAIL_USERNAME = 'user';
+      checkEmailConfig();
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('EMAIL_USERNAME and EMAIL_PASSWORD must both be set'),
+      );
+    });
+
+    it('logs a warning when only EMAIL_PASSWORD is set', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      process.env.EMAIL_PASSWORD = 'pass';
+      checkEmailConfig();
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('EMAIL_USERNAME and EMAIL_PASSWORD must both be set'),
+      );
+    });
+
+    it('does not warn when both credentials are set', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      process.env.EMAIL_USERNAME = 'user';
+      process.env.EMAIL_PASSWORD = 'pass';
+      checkEmailConfig();
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('does not warn when neither credential is set', () => {
+      process.env.EMAIL_HOST = 'smtp.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      checkEmailConfig();
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('does not warn for partial credentials when SMTP is not configured', () => {
+      process.env.EMAIL_USERNAME = 'user';
+      checkEmailConfig();
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Mailgun configuration', () => {
+    it('returns true with Mailgun API key, domain, and EMAIL_FROM', () => {
+      process.env.MAILGUN_API_KEY = 'key-abc123';
+      process.env.MAILGUN_DOMAIN = 'mg.example.com';
+      process.env.EMAIL_FROM = 'noreply@example.com';
+      expect(checkEmailConfig()).toBe(true);
+    });
+
+    it('returns false when Mailgun is partially configured', () => {
+      process.env.MAILGUN_API_KEY = 'key-abc123';
+      expect(checkEmailConfig()).toBe(false);
+    });
+  });
+});

packages/api/src/utils/email.ts

@@ -1,3 +1,5 @@
+import { logger } from '@librechat/data-schemas';
+
 /**
  * Check if email configuration is set
  * @returns Returns `true` if either Mailgun or SMTP is properly configured
@@ -7,10 +9,17 @@ export function checkEmailConfig(): boolean {
     !!process.env.MAILGUN_API_KEY && !!process.env.MAILGUN_DOMAIN && !!process.env.EMAIL_FROM;
 
   const hasSMTPConfig =
-    (!!process.env.EMAIL_SERVICE || !!process.env.EMAIL_HOST) &&
-    !!process.env.EMAIL_USERNAME &&
-    !!process.env.EMAIL_PASSWORD &&
-    !!process.env.EMAIL_FROM;
+    (!!process.env.EMAIL_SERVICE || !!process.env.EMAIL_HOST) && !!process.env.EMAIL_FROM;
+
+  if (hasSMTPConfig) {
+    const hasUsername = !!process.env.EMAIL_USERNAME;
+    const hasPassword = !!process.env.EMAIL_PASSWORD;
+    if (hasUsername !== hasPassword) {
+      logger.warn(
+        '[checkEmailConfig] EMAIL_USERNAME and EMAIL_PASSWORD must both be set for authenticated SMTP, or both omitted for unauthenticated SMTP.',
+      );
+    }
+  }
 
   return hasMailgunConfig || hasSMTPConfig;
 }