feat(email-resend): add Custom headers for the Resend adapter (#15645)

After some trying (and failing) to enable unsubscribe headers, I found
that the Resend adapter does not pass custom headers from the Payload
sendEmail options to the Resend API. When attempting to send an email
with custom headers, they are ignored because the
`mapPayloadEmailToResendEmail` function creates a new object that
excludes the headers property.

```
await payload.sendEmail({
  from: "Test <test@domain.com>",
  to: "jimmybillbob@example.com",
  subject: "Resend adapter does not allow custom headers :(",
  html: html,
  headers: {
    "List-Unsubscribe": "<https://domain.com/unsubscribe>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  },
});
```

I have recitified this by adding `headers: message.headers,` to the
`mapPayloadEmailToResendEmail` in `packages/email-resend/src/index.ts`,
as below.

```
function mapPayloadEmailToResendEmail(
  message: SendEmailOptions,
  defaultFromAddress: string,
  defaultFromName: string,
): ResendSendEmailOptions {
  return {
    // Required
    from: mapFromAddress(message.from, defaultFromName, defaultFromAddress),
    subject: message.subject ?? '',
    to: mapAddresses(message.to),

    // Other To fields
    bcc: mapAddresses(message.bcc),
    cc: mapAddresses(message.cc),
    reply_to: mapAddresses(message.replyTo),

    // Optional
    attachments: mapAttachments(message.attachments),
    html: message.html?.toString() || '',
    text: message.text?.toString() || '',
    headers: message.headers, // Added this line.
  } as ResendSendEmailOptions
}
```

---------

Co-authored-by: Paul Popus <paul@payloadcms.com>

Author: fdurackbrooks

packages/email-resend/src/email-resend.spec.ts

@@ -152,6 +152,88 @@ describe('email-resend', () => {
     })
   })
 
+  describe('headers', () => {
+    beforeEach(() => {
+      global.fetch = vitest.spyOn(global, 'fetch').mockImplementation(
+        vitest.fn(() =>
+          Promise.resolve({
+            json: () => ({ id: 'test-id' }),
+          }),
+        ) as Mock,
+      ) as Mock
+    })
+
+    const adapter = () =>
+      resendAdapter({ apiKey, defaultFromAddress, defaultFromName })({ payload: mockPayload })
+
+    it('should pass simple string headers through as-is', async () => {
+      await adapter().sendEmail({
+        from,
+        to,
+        subject,
+        headers: { 'List-Unsubscribe': '<mailto:unsub@example.com>' },
+      })
+
+      // @ts-expect-error
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body)
+      expect(body.headers).toStrictEqual({ 'List-Unsubscribe': '<mailto:unsub@example.com>' })
+    })
+
+    it('should join array string values with a comma', async () => {
+      await adapter().sendEmail({
+        from,
+        to,
+        subject,
+        headers: { 'X-Custom': ['val1', 'val2'] },
+      })
+
+      // @ts-expect-error
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body)
+      expect(body.headers).toStrictEqual({ 'X-Custom': 'val1, val2' })
+    })
+
+    it('should extract the value from prepared-object header values', async () => {
+      await adapter().sendEmail({
+        from,
+        to,
+        subject,
+        headers: { 'X-Prepared': { prepared: true, value: 'prepared-value' } },
+      })
+
+      // @ts-expect-error
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body)
+      expect(body.headers).toStrictEqual({ 'X-Prepared': 'prepared-value' })
+    })
+
+    it('should convert array-of-objects header form to a plain object', async () => {
+      await adapter().sendEmail({
+        from,
+        to,
+        subject,
+        headers: [
+          { key: 'X-First', value: 'first' },
+          { key: 'X-Second', value: 'second' },
+        ],
+      })
+
+      // @ts-expect-error
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body)
+      expect(body.headers).toStrictEqual({ 'X-First': 'first', 'X-Second': 'second' })
+    })
+
+    it('should omit the headers field when headers are undefined', async () => {
+      await adapter().sendEmail({
+        from,
+        to,
+        subject,
+      })
+
+      // @ts-expect-error
+      const body = JSON.parse(global.fetch.mock.calls[0][1].body)
+      expect(body).not.toHaveProperty('headers')
+    })
+  })
+
   it('should throw an error if the email fails to send', async () => {
     const errorResponse = {
       name: 'validation_error',

packages/email-resend/src/index.ts

@@ -82,6 +82,7 @@ function mapPayloadEmailToResendEmail(
 
     // Optional
     attachments: mapAttachments(message.attachments),
+    headers: mapHeaders(message.headers),
     html: message.html?.toString() || '',
     text: message.text?.toString() || '',
   } as ResendSendEmailOptions
@@ -162,6 +163,32 @@ function mapAttachments(
   })
 }
 
+function mapHeaders(headers: SendEmailOptions['headers']): Record<string, string> | undefined {
+  if (!headers) {
+    return undefined
+  }
+
+  // Array-of-objects form: [{ key: string; value: string }, ...]
+  if (Array.isArray(headers)) {
+    return headers.reduce<Record<string, string>>((acc, { key, value }) => {
+      acc[key] = value
+      return acc
+    }, {})
+  }
+
+  // Object form: { [key: string]: string | string[] | { prepared: boolean; value: string } }
+  return Object.entries(headers).reduce<Record<string, string>>((acc, [key, value]) => {
+    if (typeof value === 'string') {
+      acc[key] = value
+    } else if (Array.isArray(value)) {
+      acc[key] = value.join(', ')
+    } else {
+      acc[key] = value.value
+    }
+    return acc
+  }, {})
+}
+
 type ResendSendEmailOptions = {
   /**
    * Filename and content of attachments (max 40mb per email)