medusa-store/www/apps/resources/app/architectural-modules/notification/sendgrid/page.mdx

import { Table, Prerequisites } from "docs-ui"

export const metadata = {
  title: `SendGrid Notification Module Provider`,
}

# {metadata.title}

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

---

## Register the SendGrid Notification Module

<Prerequisites
  items={[
    {
      text: "SendGrid account",
      link: "https://signup.sendgrid.com",
    },
    {
      text: "Setup SendGrid single sender",
      link: "https://docs.sendgrid.com/ui/sending-email/sender-verification",
    },
    {
      text: "SendGrid API Key",
      link: "https://docs.sendgrid.com/ui/account-and-settings/api-keys",
    },
  ]}
/>

Add the module into the `providers` array of the Notification Module:

<Note>

Only one provider can be defined for a channel.

</Note>

```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"

// ...

module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          // ...
          {
            resolve: "@medusajs/medusa/notification-sendgrid",
            id: "sendgrid",
            options: {
              channels: ["email"],
              api_key: process.env.SENDGRID_API_KEY,
              from: process.env.SENDGRID_FROM,
            },
          },
        ],
      },
    },
  ],
})
```

### Environment Variables

Make sure to add the following environment variables:

```bash
SENDGRID_API_KEY=<YOUR_SENDGRID_API_KEY>
SENDGRID_FROM=<YOUR_SENDGRID_FROM>
```

### SendGrid Notification Module Options

<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>Option</Table.HeaderCell>
      <Table.HeaderCell>Description</Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>`channels`</Table.Cell>
      <Table.Cell>
        The channels this notification module is used to send notifications for.
        Only one provider can be defined for a channel.
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>`api_key`</Table.Cell>
      <Table.Cell>The SendGrid API key.</Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>`from`</Table.Cell>
      <Table.Cell>The SendGrid from email.</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

## SendGrid Templates

When you send a notification, you must specify the ID of the template to use in SendGrid.

Refer to [this SendGrid documentation guide](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates) on how to create templates for your different email types.

---

## Test out the Module

To test the module out, create a simple subscriber 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."],
  [
    "15",
    '"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."],
]

```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
import type {
  SubscriberArgs,
  SubscriberConfig,
} from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"

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

  const product = await productModuleService.retrieveProduct(data.id)

  await notificationModuleService.createNotifications({
    to: "test@gmail.com",
    channel: "email",
    template: "product-created",
    data: {
      product_title: product.title,
      product_image: product.images[0]?.url,
    },
  })
}

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

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.
- 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.

Then, start the Medusa application:

```bash npm2yarn
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.