docs: update examples in sendgrid guide (#12504)

* initial * docs: update examples in sendgrid guide * add note for local file module
2025-05-15 19:13:15 +03:00
parent e91aa2493a
commit 04acc5d219
5 changed files with 13487 additions and 13322 deletions
@@ -8,8 +8,6 @@ export const metadata = {

 The SendGrid Notification Module Provider integrates [SendGrid](https://sendgrid.com) to send emails to users and customers.

---
-
 ## Register the SendGrid Notification Module

 <Prerequisites
@@ -113,18 +111,21 @@ Refer to [this SendGrid documentation guide](https://docs.sendgrid.com/ui/sendin

 ## Test out the Module

-To test the module out, create a simple subscriber at `src/subscribers/product-created.ts` with the following content:
+To test the module out, you'll listen to the `product.created` event and send an email when a product is created.
+
+Create a [subscriber](!docs!/learn/fundamentals/events-and-subscribers) at `src/subscribers/product-created.ts` with the following content:

 export const highlights = [
  ["11", "notificationModuleService", "Resolve the Notification Module."],
-  ["13", "createNotifications", "Create the notification to be sent."],
+  ["14", "product", "Retrieve the product's details."],
+  ["22", "createNotifications", "Create the notification to be sent."],
  [
-    "15",
+    "24",
    '"email"',
    "By specifying the `email` channel, SendGrid will be used to send the notification.",
  ],
-  ["16", '"product-created"', "The ID of the template defined in SendGrid."],
-  ["17", "data", "The data to pass to the template defined in SendGrid."],
+  ["25", '"product-created"', "The ID of the template defined in SendGrid."],
+  ["26", "data", "The data to pass to the template defined in SendGrid."],
 ]

 ```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
@@ -139,9 +140,15 @@ export default async function productCreateHandler({
  container,
 }: SubscriberArgs<{ id: string }>) {
  const notificationModuleService = container.resolve(Modules.NOTIFICATION)
-  const productModuleService = container.resolve(Modules.PRODUCT)
+  const query = container.resolve("query")

-  const product = await productModuleService.retrieveProduct(data.id)
+  const { data: [product] } = await query.graph({
+    entity: "product",
+    fields: ["*"],
+    filters: {
+      id: data.id,
+    },
+  })

  await notificationModuleService.createNotifications({
    to: "test@gmail.com",
@@ -161,8 +168,8 @@ export const config: SubscriberConfig = {

 In this subscriber, you:

- Resolve the Notification and Product Modules' main services from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
- Retrieve the product's details to pass them to the template in SendGrid.
+- Resolve the Notification Module's main service and [Query](!docs!/learn/fundamentals/module-links/query) from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
+- Retrieve the product's details using Query to pass them to the template in SendGrid.
 - Use the `createNotifications` method of the Notification Module's main service to create a notification to be sent to the specified email. By specifying the `email` channel, the SendGrid Notification Module Provider is used to send the notification.
 - The `template` property of the `createNotifications` method's parameter specifies the ID of the template defined in SendGrid.
 - The `data` property allows you to pass data to the template in SendGrid. For example, the product's title and image.
@@ -174,3 +181,85 @@ npm run dev
 ```

 And create a product either using the [API route](!api!/admin#products_postproducts) or the [Medusa Admin](!user-guide!/products/create). This runs the subscriber and sends an email using SendGrid.
+
+### Other Events to Handle
+
+Medusa emits other events that you can handle to send notifications using the SendGrid Notification Module Provider, such as `order.placed` when an order is placed.
+
+Refer to the [Events Reference](/references/events) for a complete list of events emitted by Medusa.
+
+### Sending Emails with SendGrid in Workflows
+
+You can also send an email using SendGrid in any [workflow](!docs!/learn/fundamentals/workflows). This allows you to send emails within your custom flows.
+
+You can use the [sendNotifcationStep](!resources!/references/medusa-workflows/steps/sendNotificationsStep) in your workflow to send an email using SendGrid.
+
+For example:
+
+```ts title="src/workflows/send-email.ts"
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+import { 
+  sendNotificationsStep, 
+  useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+
+type WorkflowInput = {
+  id: string
+}
+
+export const sendEmailWorkflow = createWorkflow(
+  "send-email-workflow",
+  ({ id }: WorkflowInput) => {
+    const { data: products } = useQueryGraphStep({
+      entity: "product",
+      fields: [
+        "*",
+        "variants.*",
+      ],
+      filters: {
+        id,
+      },
+    })
+
+    sendNotificationsStep({
+      to: "test@gmail.com",
+      channel: "email",
+      template: "product-created",
+      data: {
+        product_title: product[0].title,
+        product_image: product[0].images[0]?.url,
+      },
+    })
+  }
+)
+```
+
+This workflow works similarly to the subscriber. It retrieves the product's details using Query and sends an email using SendGrid (by specifying the `email` channel) to the `test@gmail.com` email.
+
+You can also execute this workflow in a subscriber. For example, you can execute it when a product is created:
+
+```ts title="src/subscribers/product-created.ts"
+import type {
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/framework"
+import { Modules } from "@medusajs/framework/utils"
+import { sendEmailWorkflow } from "../workflows/send-email"
+
+export default async function productCreateHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await sendEmailWorkflow(container).run({
+    input: {
+      id: data.id,
+    },
+  })
+}
+
+export const config: SubscriberConfig = {
+  event: "product.created",
+}
+```
+
+This subscriber will run every time a product is created, and it will execute the `sendEmailWorkflow` to send an email using SendGrid.