feat(email-nodemailer): add email recipient override config (#16311)

Adds the ability to override recipients for ALL emails being sent via
sendEmail with the overrideRecipientAddress config in email adapters.

This can be used in deployed testing environments to ensure emails all
go to one address.

Author: paulpopus

packages/email-nodemailer/src/index.ts

@@ -9,6 +9,14 @@ import { InvalidConfiguration } from 'payload'
 export type NodemailerAdapterArgs = {
   defaultFromAddress: string
   defaultFromName: string
+  /**
+   * Override all emails to be sent to this address.
+   * Useful for testing.
+   */
+  overrideRecipientAddress?: string
+  /**
+   * Skip verifying the email SMTP transport.
+   */
   skipVerify?: boolean
   transport?: Transporter
   transportOptions?: SMTPConnection.Options
@@ -25,6 +33,7 @@ export const nodemailerAdapter = async (
   args?: NodemailerAdapterArgs,
 ): Promise<NodemailerAdapter> => {
   const { defaultFromAddress, defaultFromName, transport } = await buildEmail(args)
+  const overrideRecipientAddress = args?.overrideRecipientAddress
 
   const adapter: NodemailerAdapter = () => ({
     name: 'nodemailer',
@@ -34,6 +43,7 @@ export const nodemailerAdapter = async (
       return await transport.sendMail({
         from: `${defaultFromName} <${defaultFromAddress}>`,
         ...message,
+        ...(overrideRecipientAddress ? { to: overrideRecipientAddress } : {}),
       })
     },
   })

packages/email-resend/src/index.ts

@@ -6,6 +6,11 @@ export type ResendAdapterArgs = {
   apiKey: string
   defaultFromAddress: string
   defaultFromName: string
+  /**
+   * Override all emails to be sent to this address.
+   * Useful for testing.
+   */
+  overrideRecipientAddress?: string
 }
 
 type ResendAdapter = EmailAdapter<ResendResponse>
@@ -29,9 +34,14 @@ export const resendAdapter = (args: ResendAdapterArgs): ResendAdapter => {
     defaultFromAddress,
     defaultFromName,
     sendEmail: async (message) => {
+      const modifiedMessage = {
+        ...message,
+        ...(args.overrideRecipientAddress ? { to: args.overrideRecipientAddress } : {}),
+      }
+
       // Map the Payload email options to Resend email options
       const sendEmailOptions = mapPayloadEmailToResendEmail(
-        message,
+        modifiedMessage,
         defaultFromAddress,
         defaultFromName,
       )

test/email-nodemailer/config.ts

@@ -16,20 +16,22 @@ export default buildConfigWithDefaults({
   collections: [],
   email: nodemailerAdapter(),
   onInit: async (payload) => {
-    await payload.create({
-      collection: 'users',
-      data: {
-        email: devUser.email,
-        password: devUser.password,
-      },
-    })
+    if (process.env.SKIP_ON_INIT !== 'true') {
+      await payload.create({
+        collection: 'users',
+        data: {
+          email: devUser.email,
+          password: devUser.password,
+        },
+      })
 
-    const email = await payload.sendEmail({
-      subject: 'This was sent on init',
-      to: 'test@example.com',
-    })
+      const email = await payload.sendEmail({
+        subject: 'This was sent on init',
+        to: 'test@example.com',
+      })
 
-    payload.logger.info({ email, msg: 'Email sent' })
+      payload.logger.info({ email, msg: 'Email sent' })
+    }
   },
   typescript: {
     outputFile: path.resolve(dirname, 'payload-types.ts'),

test/email-nodemailer/int.spec.ts

@@ -0,0 +1,107 @@
+import type { NodemailerAdapterArgs } from '@payloadcms/email-nodemailer'
+import type { Payload } from 'payload'
+
+import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest'
+
+import { initPayloadInt } from '../__helpers/shared/initPayloadInt.js'
+
+let payload: Payload
+let mockedSendEmail: Mock
+
+const overrideRecipientAddress = 'overriden@example.com'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+type EmailReturnType = {
+  subject: string
+  text: string
+  to: string
+}
+
+describe('@payloadcms/email-nodemailer', () => {
+  beforeAll(async () => {
+    process.env.SKIP_ON_INIT = 'true'
+    ;({ payload } = await initPayloadInt(dirname))
+
+    mockedSendEmail = vi.fn()
+  })
+
+  afterAll(async () => {
+    if (typeof payload?.db?.destroy === 'function') {
+      await payload.db.destroy()
+    }
+  })
+
+  describe('without basic config', () => {
+    beforeEach(async () => {
+      // Partially mocked transport
+      const mockedTransport = {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        sendMail: async (message) => {
+          mockedSendEmail()
+          return message
+        },
+      } as NodemailerAdapterArgs['transport']
+
+      const adapter = await nodemailerAdapter({
+        defaultFromAddress: 'test@example.com',
+        defaultFromName: 'Test',
+        skipVerify: true,
+        transport: mockedTransport,
+      })
+
+      const mockedAdapter = adapter({ payload })
+
+      payload.email = mockedAdapter
+    })
+
+    it('sends email with overrideRecipientAddress', async () => {
+      const email = (await payload.email.sendEmail({
+        to: 'dev@example.com',
+        text: 'Hello, world!',
+        subject: 'Test email',
+      })) as EmailReturnType
+
+      expect(email.to).toEqual('dev@example.com')
+    })
+  })
+
+  describe('with overrideRecipientAddress', () => {
+    beforeEach(async () => {
+      // Partially mocked transport
+      const mockedTransport = {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        sendMail: async (message) => {
+          mockedSendEmail()
+          return message
+        },
+      } as NodemailerAdapterArgs['transport']
+
+      const adapter = await nodemailerAdapter({
+        overrideRecipientAddress,
+        defaultFromAddress: 'test@example.com',
+        defaultFromName: 'Test',
+        skipVerify: true,
+        transport: mockedTransport,
+      })
+
+      const mockedAdapter = adapter({ payload })
+
+      payload.email = mockedAdapter
+    })
+
+    it('sends email with overrideRecipientAddress', async () => {
+      const email = (await payload.email.sendEmail({
+        to: 'dev@example.com',
+        text: 'Hello, world!',
+        subject: 'Test email',
+      })) as EmailReturnType
+
+      expect(email.to).toEqual(overrideRecipientAddress)
+    })
+  })
+})