Getting Started

Medusa is a community-driven open-source platform providing out-of-the-box features for developers and non-technical folks to build their eCommerce stores in minutes. With a robust RESTful API and features for a GraphQL endpoint, Medusa also serves as a headless eCommerce engine with APIs for your independent front-end store.

Execute the create-medusa-app command below to bootstrap a V2 Medusa project containing a Node.js server and an admin dashboard for managing your commerce store.

1npx create-medusa-app@latest

With Medusa setup, let’s install and configure the medusa-plugin-smtp package for emails.

Configuring Medusa-Plugin-SMTP

The medusa-plugin-smtp package wraps around Medusa’s subscriber events and uses Nodemailer and the email-templates packages underneath to send emails when specific Medusa events are triggered.

As the name implies, the medusa-plugin-smtp package works for various SMTP providers such as Hostinger, Zoho, AWS Simple Email Service (SES). Make sure to check the Medusa Plugin library as there might be other packages specifically written for the SMTP provider you are making use of such as medusa-plugin-sendgrid for Sendgrid .

Install the medusa-plugin-smtp package as a dependency into your medusa project;

1yarn add medusa-plugin-smtp

Next, open the medusa-config.js file for your Medusa project in your preferred code editor as the next step involves modifying the default configuration.

Add the following object into the plugins array within the medusa-config.js file to register the medusa-plugin-smtp package as a plugin.

1  {
2    resolve: "medusa-plugin-smtp",
3    options: {
4      fromEmail: EMAIL_SENDER_ADDRESS,
5      transport: {
6        sendmail: true,
7        path: "/usr/sbin/sendmail",
8        newline: "unix",
9      },
10      host: "smtp.zoho.com",
11      port: 465,
12      secureConnection: false,
13      auth: {
14        user: EMAIL_SENDER_USER,
15        pass: EMAIL_SENDER_PASS,
16      },
17      preview: false, 
18      tls: {
19        ciphers: "SSLv3",
20      },
21      requireTLS: false,
22      emailTemplatePath: "data/emailTemplates",
23      templateMap: {
24        "invite.created": "inviteCreated",
25        "order.placed": "orderPlaced",
26      },
27    },
28  },

While the object above contains multiple string, boolean, and nested object properties, the following list explains the most important properties and their use;

• auth — this object contains your SMTP server authentication details. Always retrieve the user and pass values from your environment variables and do not hardcode them in the medusa-config.js file for security reasons.

• emailTemplatePath — this value specifies the directory of your email templates within the Medusa project. You must create the directories for the email templates manually. Each sub-directory within the root maps to an email template.
  
  As shown in the following image, the emailTemplates directory contains an inviteCreated and orderCreated sub-directories.
  
  

• templateMap — as the name implies, this subscribes the medusa-plugin-smtp plugin to a Medusa event and sends the matching email template.

For the object within the code block, the invite.created and order.placed events have been mapped to send out an email when a user is invited to your Medusa Admin and an order is placed.

Designing An Email Template

By default, the medusa-plugin-smtp package uses PUG templates to render HTML emails. Pug provides features to inject dynamic data about the event such as the order details, or customer data.

Open the html.pug file and add the following code which renders an email to welcome the recipient to the Medusa Admin dashboard.

1doctype html
2html
3  head
4    title Welcome to Our Medusa Admin Dashboard!
5  body
6    p Hello #{data.user_email}, 
7    p We're excited to invite you to join our Admin Dashboard. This is your gateway to managing operations, tracking sales, and keeping everything running smoothly.
8    p Please navigate to the Medusa Admin Dashboard to get started.

The email template above uses the string interpolation feature of Pug to insert the user’s email for personalization. Medusa will pass in a data object payload relating to the triggered event for you to render in your pug templates.

Testing Your Email Template

Testing the email templates in your Medusa project involves performing an action to trigger the mapped email event, such as completing a chart checkout or creating a customer account.

The quickest way to trigger an email template from the Medusa Admin dashboard is to invite a user to the management team. Medusa will trigger the invite.created event to send the inviteCreated email template.

Navigate to the Settings > Team page of your Medusa dashboard and invite a user to your project.

When Medusa processes the invite.created event, medusa-plugin-smtp will launch a browser tab to preview the rendered email template because your project is running in development mode.

If you want to disable previews of the email template, you need to specify a preview property in the configuration object within the medusa-config.js file.

Wrap Up

The medusa-plugin-smtp package performs its core functionality of sending emails in your Medusa project, even though it might be difficult to configure due to its limited documentation and limited error logging.