Mailer

Medusa Plugin Mailer

Send transactional emails from your Medusa v2 store when things happen — orders placed, shipments created, customers signed up, and more.

You pick which events matter, point them at HTML templates, and the plugin delivers over SMTP. Nothing is sent until you create an active mapping in the admin.

Medusa Website | Medusa Repository | Medusa Documentation

Features

• Listen to a fixed set of Medusa events (orders, shipments, customers, returns, and optional custom events).
• Map each event to a template, subject line, and variable paths in the admin UI.
• Store mappings in the database — no seeds, no hidden defaults.
• Ship generic HTML templates out of the box, or point to your own folder.
• Send through SMTP with one or more “from” profiles.
• Test sends from the admin without waiting for a real order.
• Load order, fulfillment, and customer data automatically when resolving template variables.

Prerequisites

• Node.js v20 or greater
• A Medusa v2 backend
• An SMTP provider (e.g. your host’s mail relay, Brevo, Amazon SES, Postmark, Gmail app password, etc.)
• Optional: a storefront URL and logo URL for branding in templates

How to Install

1. In your Medusa backend directory, install the plugin and Nodemailer:

   1npm install @sam-ael/medusa-plugin-mailer nodemailer
   2# or
   3yarn add @sam-ael/medusa-plugin-mailer nodemailer

2. Add the plugin to your medusa-config plugins list:

   1// medusa-config.ts
   2module.exports = defineConfig({
   3  // ...
   4  plugins: [
   5    // ...
   6    {
   7      resolve: "@sam-ael/medusa-plugin-mailer",
   8      options: {},
   9    },
   10  ],
   11})

3. Set environment variables in .env (see Configuration for the full list):

   1MAILER_SMTP_HOST=smtp.example.com
   2MAILER_SMTP_PORT=587
   3MAILER_SMTP_USER=your-user
   4MAILER_SMTP_PASS=your-password
   5MAILER_SMTP_SECURE=false
   6
   7MAILER_FROM_NAME_1=My Store
   8MAILER_FROM_ADDRESS_1=no-reply@example.com
   9
   10MAILER_TEMPLATES_DIR=src/email_templates
   11
   12STORE_NAME=My Store
   13STORE_URL=https://www.example.com

4. Run migrations so the mapping table exists:

   npx medusa db:migrate

   This creates an empty mailer_event_mapping table. It does not insert any mappings for you.

5. Start the backend and open the admin. You should see Mailer in the sidebar.

6. Create at least one active mapping (event → template → variables). Until you do that, the plugin will not send mail for that event.

Configuration

Environment variables

If SMTP is incomplete, the plugin logs a warning and skips sending instead of crashing.

How events and mappings fit together

Think of two layers:

1. What the plugin listens for — a fixed list of event names in the plugin code (MAILER_EVENTS). You cannot turn listening on/off in the database; you only map the ones you care about.
2. What actually gets emailed — rows you create in Admin (or via API). Each row ties an event name to a template file, subject, variable map, recipient rule, and an active flag.

No active mapping ⇒ no email, even if the event fires.

Template placeholders

Templates use Go-style variables:

1<p>Hi {{ .first_name }},</p>
2<p>Order #{{ .display_id }} is confirmed.</p>

Always available without mapping:

Your mapping’s template variables object maps each name to a data path on the loaded entity, for example:

1{
2  "first_name": "customer.first_name",
3  "display_id": "display_id",
4  "total": "total"
5}

Unmatched {{ .Something }} placeholders are removed before the message is sent.

Recipient types

Events the plugin listens to

These names are hardcoded. Map only the ones you need.

Orders

Fulfillment

Prefer the Medusa core-flows names:

Legacy aliases still listen if something emits them: fulfillment.created, fulfillment.shipment_created, fulfillment.delivery_created.

Customers & RMA

Optional custom events

Your app can emit these; the plugin will handle them if you add mappings. Payloads are not graph-hydrated — put the fields you need on the event data and map paths like amount → amount.

Example emit from your backend:

1import { Modules } from "@medusajs/framework/utils"
2
3const eventBus = container.resolve(Modules.EVENT_BUS)
4
5await eventBus.emit({
6  name: "loyalty.points_credited",
7  data: {
8    email: "customer@example.com",
9    amount: 100,
10    balance: 500,
11    description: "Thanks for your order",
12  },
13})

What gets loaded for common events

Bundled templates

The package ships plain, unbranded HTML under email_templates/. Use them as-is or copy them into your MAILER_TEMPLATES_DIR and redesign.

Brand with STORE_NAME and optional MAILER_LOGO_URL. Regenerate the defaults from the plugin repo with:

node scripts/generate-bundled-templates.mjs

Suggested mapping examples

Order confirmation

• Event: order.placed

• Template: order_placed.html

• Subject: Order #{{ .display_id }} confirmed

• Recipient: Order email

• Variables:

  Name	Path
  first_name	customer.first_name
  display_id	display_id
  total	total

Shipment

• Event: shipment.created

• Template: order_shipped.html

• Subject: Your order is on the way

• Variables:

  Name	Path
  first_name	order.customer.first_name
  display_id	order.display_id
  tracking_number	labels.0.tracking_number
  tracking_url	labels.0.tracking_url
  carrier	provider_id

Test the Plugin

1. Run your Medusa backend:

   1npm run dev
   2# or
   3npx medusa develop

2. Open Admin → Mailer and check that SMTP shows as configured.

3. Create an active mapping for order.placed → order_placed.html (or your own template).

4. Either:

   • Place a test order in a storefront / Store API, or
   • Use Send email in the Mailer admin with a test address and sample variables.

5. Confirm the message arrives and that placeholders look correct.

If nothing arrives: check SMTP env vars, that the mapping is active, and that the event name matches the list above (for shipping, prefer shipment.created).

Admin API (optional)

Useful for automation or custom UIs. All routes require an authenticated admin user.

You can also trigger the same pipeline from code:

1import { sendEventEmailsWorkflow } from "@sam-ael/medusa-plugin-mailer/workflows"
2
3await sendEventEmailsWorkflow(container).run({
4  input: {
5    event_name: "order.placed",
6    event_data: { id: orderId },
7  },
8})

Troubleshooting

Develop this repository

1yarn install
2yarn build      # produces .medusa/server
3yarn typecheck
4yarn test

Peer dependencies should match your host Medusa version as closely as practical.

Additional Resources

• Medusa documentation
• Medusa events & subscribers
• Medusa plugins
• Nodemailer

License

MIT