Skip to main content
Skip to main content

SendGrid

In this document, you’ll learn about the SendGrid plugin, what it does, and how to use it.

Overview​

SendGrid is an email and notification service that can be used to send emails to your customers and users.

By integrating SendGrid with Medusa, you’ll be sending email notifications to your users in the following cases:

  1. Order-related events include new orders, shipments created, and orders canceled.
  2. Swaps and Returns related events including new return requests of orders and items returned successfully.
  3. When Gift Cards in an order are created.
  4. User-related events including reset passwords.
  5. Restock Notifications for when product stocks are low.

You can also handle custom events.

Prerequisites​

Before going further with this guide make sure you have a Medusa backend set up. You can follow the Quickstart guide. The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.

Create a SendGrid Account​

If you don’t have a SendGrid account, make sure to create one first. You also need to set up a single sender first in SendGrid before you can start sending emails.

API Key​

For the integration to work, you need to create an API key in your SendGrid account.

You can do that by choosing from the sidebar of your SendGrid dashboard Settings > API Keys. Then, click on Create API Key.

Note

If you choose to give the API Key restricted access, make sure to at least give it the “Mail Send” access.

Once you create the API key, the key will be shown for one time only. Make sure to copy and save it somewhere for later usage.

Email Templates​

The SendGrid plugin uses SendGrid templates to send emails. If you don’t provide the plugin with the templates necessary then emails will not be sent.

To create an email template, go to Email API > Dynamic Templates. Then, click “Create a Dynamic Template”. You’ll then be able to see the Template ID which you’ll need for your plugin setup.

When you create the dynamic templates you’ll be able to use variables sent from Medusa using Handlebars.

For a full list of templates and their variables please check out the Template Reference.

Tip

Medusa supports localization so you can also create multiple templates for multiple languages.

Install the SendGrid Plugin​

In the directory of your Medusa backend run the following command to install the SendGrid plugin:

npm install medusa-plugin-sendgrid

Then, in your .env file add the API key you created earlier as well as the send from email:

SENDGRID_API_KEY=<API_KEY>
SENDGRID_FROM=<SEND_FROM_EMAIL>

Make sure to replace the <API_KEY> with the SendGrid API key and the <SEND_FROM_EMAIL> with the email you’re using in SendGrid as the single sender.

Also, you should add the ID of each template you create in .env as well. For example:

SENDGRID_ORDER_PLACED_ID=<ORDER_PLACED_TEMPLATE_ID>

Where <ORDER_PLACED_TEMPLATE_ID is the ID of your template for order placed emails.

Finally, in your medusa-config.js file, add the SendGrid plugin into the array of plugins:

medusa-config.js
const plugins = [
  // ...,
  {
    resolve: `medusa-plugin-sendgrid`,
    options: {
      api_key: process.env.SENDGRID_API_KEY,
      from: process.env.SENDGRID_FROM,
      order_placed_template: 
        process.env.SENDGRID_ORDER_PLACED_ID,
      localization: {
        "de-DE": { // locale key
          order_placed_template:
            process.env.SENDGRID_ORDER_PLACED_ID_LOCALIZED,
        },
      },
    },
  },
]

The api_key and from options are required. Then, use the key of each template you create (from the reference) as the option name with the template ID as the value.

You can also optionally pass the option localization if you want to support different languages. localization accepts an object that has the country and language codes as keys. The value for each code should be an object of template keys and their IDs as values. Make sure to include the localized template IDs in .env as well.

Important

The keys you add should also be present in the context field of the cart under the locale key cart.context.locale. This is crucial to ensure that the templates are used correctly based on the cart's localization.

Custom Templates​

Aside from the supported templates defined in the reference section, you may specify templates for Medusa defined or custom events.

For example:

medusa-config.js
const plugins = [
  // ...,
  {
    resolve: `medusa-plugin-sendgrid`,
    options: {
      // other options...
      product_created_template: 
        process.env.SENDGRID_ORDER_CREATED_ID,
      my_custom_event_template:
        process.env.SENDGRID_CUSTOM_EVENT_ID,
    },
  },
]

Make sure to replace every . in the event's name with a _.

When a template is specified for an event that isn't mentioned in the reference, the data passed to the template is the data payload of the event.

Tip

Refer to the events reference for the expected payload of Medusa events.

Test it Out​

Run your backend now:

npx medusa develop

To test it out, perform an action that would trigger one of the emails being sent. For example, you can use your Medusa storefront to create an order. An email from your SendGrid account will be sent to the customer email.

Tip

If you don’t have a storefront installed, check out the Next.js Starter Template.

You can also track analytics related to emails sent from the SendGrid dashboard.

SendGrid Analytics

Dynamic usage​

You can resolve the SendGrid service to send emails from your custom services or other resources.

For example, in an API Route:

src/api/store/email/route.ts
import type { 
  MedusaRequest, 
  MedusaResponse,
} from "@medusajs/medusa"

export const POST = async (
  req: MedusaRequest, 
  res: MedusaResponse
) => {
  const sendgridService = req.scope.resolve("sendgridService")
  const sendOptions =  {
      templateId: "d-123....",
      from: "ACME <acme@mail.com>",
      to: "customer@mail.com",
      dynamic_template_data: { dynamic: "data" },
    }
    sendgridService.sendEmail(sendOptions)
}

Template Reference​

This section covers the template types supported by the plugin and what variables you can expect in your dynamic template. You can use the variables to add details like order total or customer name.

Note

You don’t have to create a template for every type in the reference. You can simply create templates for the type of emails you want to send.

Order Placed​

Key in plugin options: order_placed_template

Description: Template to be sent to the customer when they place a new order.

Example Data

Order Canceled​

Key in plugin options: order_canceled_template

Description: Template to be sent to a customer when their order is canceled.

Example Data

Order Shipment Created​

Key in plugin options: order_shipped_template

Description: Template to be sent to the customer when a shipment of their order has been created.

Example Data

Order Return Requested​

Key in plugin options: order_return_requested_template

Description: Template to be sent to the customer when a return request is made for an order.

Example Data

Order Items Returned​

Key in plugin options: order_items_returned_template

Description: Template to be sent to the customer when an order’s items have been returned.

Example Data

Claim Shipment Created​

Key in plugin options: claim_shipment_created_template

Description: Template to be sent to the customer when a Claim shipment has been created.

Example Data

Swap Created​

Key in plugin options: swap_created_template

Description: Template to be sent to the customer when a swap for an order has been created.

Example Data

Swap Shipment Created​

Key in plugin options: swap_shipment_created_template

Description: Template to be sent to the customer when a shipment of a swap of an order has been created.

Example Data

Swap Received​

Key in plugin options: swap_received_template

Description: Template to be sent to the customer when a swap of an order has been received.

Example Data

Gift Card Created​

Key in plugin options: gift_card_created_template

Description: Template to be to the customer sent when a gift card in their order has been created.

Example Data

Customer Password Reset​

Key in plugin options: customer_password_reset_template

Description: Template to be sent to the customer when they request a password reset.

Example Data

User Password Reset​

Key in plugin options: user_password_reset_template

Description: Template to be sent to the admin user when they request a password reset.

Example Data

Restock Notification​

Key in plugin options: medusa_restock_template

Description: Template to be sent to admin users when a product has hit the restock quantity threshold.

Example Data

See Also​

Was this section helpful?
© 2024 Medusa, Inc. All rights reserved.