feat: add support for custom arguments in Twilio Sendgrid email notifications (#14879)

## Summary

**What** — What changes are introduced in this PR?

*Added support for passing SendGrid personalizations directly via provider_data in the notification payload.*

**Why** — Why are these changes relevant or necessary?  

*This allows callers to pass any SendGrid-native personalization data (e.g. customArgs for analytics/event tracking, per-recipient overrides, dynamic template data per recipient) without the provider needing to know about each specific field.*

**How** — How have these changes been implemented?

*Modified the SendgridNotificationService.send() method to check notification.provider_data.personalizations. When present and non-empty, it is forwarded directly to the SendGrid send() call and the top-level to field is omitted (since personalizations handles recipient routing). When absent or empty, the existing behavior using the top-level to field is preserved unchanged.*

**Testing** — How have these changes been tested, or how can the reviewer test the feature?

*Unit tests added in integration-tests/__tests__/services.spec.ts using a mocked @sendgrid/mail. Three cases are covered: personalizations present and forwarded, absent (falls back to top-level to), and empty array (also falls back to top-level to).*

resolves #15115 
---

## Examples

Provide examples or code snippets that demonstrate how this feature works, or how it can be used in practice.  
This helps with documentation and ensures maintainers can quickly understand and verify the change.

```ts
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
import { INotificationModuleService } from "@medusajs/framework/types"

export default async function productCreateHandler({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  const notificationModuleService: INotificationModuleService =
    container.resolve(Modules.NOTIFICATION)

  const emailData = {
    name: "Sample Product",
    message: `New product created with id ${data.id}`,
  }

  const email = await notificationModuleService.createNotifications({
    to: "xxxxx@xxxx.com",
    channel: "email",
    template: "xxxxxxxxxx",
    data: emailData,
    provider_data: {
      personalizations: [
        {
          to: [{ email: "xxxxx@xxxx.com" }],
          customArgs: {
            customer_id: "cust_abc",
            ga4_id: "GA1.2.xxxxx",
            notification_type: "order_confirmation",
          },
        },
      ],
    },
  })
}

export const config: SubscriberConfig = {
  event: "product.created",
}
```

---

## Checklist

Please ensure the following before requesting a review:

- [x] I have added a **changeset** for this PR
    - Every non-breaking change should be marked as a **patch**
    - To add a changeset, run `yarn changeset` and follow the prompts
- [x] The changes are covered by relevant **tests**
- [x] I have verified the code works as intended locally
- [x] I have linked the related issue(s) if applicable

---

## Additional Context

Add any additional context, related issues, or references that might help the reviewer understand this PR.


---

> [!NOTE]
> **Low Risk**
> Low risk: small, additive change to the SendGrid payload; main risk is passing unexpected `provider_data.custom_args` values, mitigated by coercing all values to strings.
> 
> **Overview**
> Adds support for SendGrid `customArgs` by reading `notification.provider_data.custom_args`, coercing values to strings, and including the result in the outgoing `sendgrid.send()` message payload.
> 
> Includes a changeset bumping `@medusajs/notification-sendgrid` as a minor release to document the new capability.
> 
> <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 69b1ef0. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>

Author: 420coupe

.changeset/forty-states-invent.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/notification-sendgrid": patch
+---
+
+feat(notification-sendgrid): add support for personalizations via provider_data

packages/modules/providers/notification-sendgrid/integration-tests/__tests__/services.spec.ts

@@ -1,6 +1,100 @@
+import sendgrid from "@sendgrid/mail"
 import { SendgridNotificationService } from "../../src/services/sendgrid"
+
+jest.mock("@sendgrid/mail", () => ({
+  __esModule: true,
+  default: {
+    setApiKey: jest.fn(),
+    send: jest.fn().mockResolvedValue([{ statusCode: 202 }, {}]),
+  },
+}))
+
+jest.mock("@medusajs/framework/utils", () => ({
+  AbstractNotificationProviderService: class {},
+  MedusaError: class MedusaError extends Error {
+    static Types = {
+      INVALID_DATA: "invalid_data",
+      UNEXPECTED_STATE: "unexpected_state",
+    }
+    type: string
+    constructor(type: string, message: string) {
+      super(message)
+      this.type = type
+    }
+  },
+}), { virtual: true })
+
+const mockSend = sendgrid.send as jest.MockedFunction<typeof sendgrid.send>
+
 jest.setTimeout(100000)
 
+describe("SendgridNotificationService - personalizations", () => {
+  let service: SendgridNotificationService
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    service = new SendgridNotificationService(
+      { logger: console as any },
+      { api_key: "test-api-key", from: "sender@example.com" }
+    )
+  })
+
+  it("passes provider_data.personalizations directly to sendgrid and omits top-level to", async () => {
+    await service.send({
+      to: "recipient@example.com",
+      channel: "email",
+      template: "some-template",
+      provider_data: {
+        personalizations: [
+          {
+            to: [{ email: "recipient@example.com" }],
+            customArgs: { campaign_id: "abc123", source: "welcome-flow" },
+          },
+        ],
+      },
+    })
+
+    expect(mockSend).toHaveBeenCalledTimes(1)
+    const message = mockSend.mock.calls[0][0] as any
+    expect(message).not.toHaveProperty("to")
+    expect(message.personalizations).toEqual([
+      {
+        to: [{ email: "recipient@example.com" }],
+        customArgs: { campaign_id: "abc123", source: "welcome-flow" },
+      },
+    ])
+  })
+
+  it("uses top-level to and omits personalizations when provider_data.personalizations is absent", async () => {
+    await service.send({
+      to: "recipient@example.com",
+      channel: "email",
+      template: "some-template",
+    })
+
+    expect(mockSend).toHaveBeenCalledTimes(1)
+    const message = mockSend.mock.calls[0][0] as any
+    expect(message.to).toEqual("recipient@example.com")
+    expect(message).not.toHaveProperty("personalizations")
+  })
+
+  it("falls back to top-level to when provider_data.personalizations is an empty array", async () => {
+    await service.send({
+      to: "recipient@example.com",
+      channel: "email",
+      template: "some-template",
+      provider_data: {
+        personalizations: [],
+      },
+    })
+
+    expect(mockSend).toHaveBeenCalledTimes(1)
+    const message = mockSend.mock.calls[0][0] as any
+    expect(message.to).toEqual("recipient@example.com")
+    expect(message).not.toHaveProperty("personalizations")
+  })
+})
+
 // Note: This test hits the sendgrid service, and it is mainly meant to be run manually after setting all the envvars below.
 // We could also setup a sink email service to test this automatically, but it is not necessary for the time being.
 describe.skip("Sendgrid notification provider", () => {

packages/modules/providers/notification-sendgrid/src/services/sendgrid.ts

@@ -79,13 +79,17 @@ export class SendgridNotificationService extends AbstractNotificationProviderSer
       }
     }
 
+    const personalizations = notification.provider_data?.personalizations as
+      | sendgrid.MailDataRequired["personalizations"]
+      | undefined
+
     const message: sendgrid.MailDataRequired = {
-      to: notification.to,
       from: from,
       dynamicTemplateData: notification.data as
         | { [key: string]: any }
         | undefined,
       attachments: attachments,
+      ...(personalizations?.length ? { personalizations } : { to: notification.to }),
       ...mailContent,
     }