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>

```js title="medusa-config.js"
const { Modules } = require("@medusajs/framework/utils")

// ...

module.exports = defineConfig({
  // ...
  modules: {
    [Modules.NOTIFICATION]: {
      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 = [
  ["12", "notificationModuleService", "Resolve the Notification Module."],
  ["15", "create", "Create the notification to be sent."],
  [
    "17",
    '"email"',
    "By specifying the `email` channel, SendGrid will be used to send the notification.",
  ],
  ["18", '"product-created"', "The ID of the template defined in SendGrid."],
  ["19", "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"
import { INotificationModuleService } from "@medusajs/framework/types"

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

  await notificationModuleService.createNotifications({
    to: "test@gmail.com",
    from: "test@medusajs.com", // Optional var, verified sender required
    channel: "email",
    template: "product-created",
    data,
    attachments: [ // optional var
      {
        content: base64,
        content_type: "image/png", // mime type
        filename: filename.ext,
        disposition: "attachment or inline attachment",
        id: "id", // only needed for inline attachment
      },
    ],
  })
}

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

In this subscriber:

- Resolve the Notification Module's main service.
- Use the `create` method of the 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 `create` 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.
- The `attachments` optional property allows you to pass attachments to the template in SendGrid.
- The `from` optional property allows you to pass a single sender-verified email. If not provided, the value of the `from` configuration of the module is used.

Then, start the Medusa application:

```bash npm2yarn
npm run dev
```

{/* TODO add links */}

And create a product either using the [API route](!api!/api/admin#products_postproducts) or the Medusa Admin. This runs the subscriber and sends an email using SendGrid.