Mailer
Send UI-managed email notifications on Medusa store events via SMTP.
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
-
In your Medusa backend directory, install the plugin and Nodemailer:
-
Add the plugin to your plugins list:
-
Set environment variables in (see Configuration for the full list):
-
Run migrations so the mapping table exists:
npx medusa db:migrateThis creates an empty table. It does not insert any mappings for you.
-
Start the backend and open the admin. You should see Mailer in the sidebar.
-
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
| Variable | Required | Description |
|---|---|---|
| Yes (to send) | SMTP host | |
| No (default ) | SMTP port | |
| Yes (to send) | SMTP username | |
| Yes (to send) | SMTP password | |
| No | Set for port 465 | |
| Yes (to send) | Display name for sender profile 1 | |
| Yes (to send) | From address for sender profile 1 | |
| … | No | Extra sender profiles (pick by index in a mapping) |
| … | No | |
| Recommended | Folder of templates (relative to process cwd or absolute). Falls back to bundled templates if missing | |
| Recommended | Used as in templates | |
| or | Recommended | Used as / |
| No | Absolute image URL for | |
| No (default ) | Parallel sends when several mappings match one event | |
| No | Set for Nodemailer debug logs | |
| No | EHLO / HELO hostname |
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:
- What the plugin listens for — a fixed list of event names in the plugin code (). You cannot turn listening on/off in the database; you only map the ones you care about.
- 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:
Always available without mapping:
| Placeholder | Source |
|---|---|
| / | or |
| resolved recipient | |
| mapping subject (after substitution) | |
| (optional) | |
| default text if you do not map it |
Your mapping’s template variables object maps each name to a data path on the loaded entity, for example:
Unmatched placeholders are removed before the message is sent.
Recipient types
| Type | Behavior |
|---|---|
| Prefer email from the order/customer graph | |
| Prefer the order’s field | |
| Use the fixed address on the mapping |
Events the plugin listens to
These names are hardcoded. Map only the ones you need.
Orders
| Event | Typical use |
|---|---|
| Order confirmation | |
| Order finished | |
| Cancellation notice | |
| Use sparingly (can be noisy) | |
| “We’re packing your order” | |
| Fulfillment canceled | |
| Return started | |
| Return received / refund note |
Fulfillment
Prefer the Medusa core-flows names:
| Event | Typical use |
|---|---|
| Shipped + tracking | |
| Delivered |
Legacy aliases still listen if something emits them: , , .
Customers & RMA
| Event |
|---|
| , |
| , |
| , |
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 → .
| Event | Example fields on |
|---|---|
| , , , , | |
| same | |
| / | , , , , |
| , , , |
Example emit from your backend:
What gets loaded for common events
| Event pattern | Hydrated data |
|---|---|
| (most) | Full order (addresses, customer, items, totals, …) |
| Order via | |
| / | Fulfillment + linked order (including tracking labels when present) |
| Custom loyalty / wallet / membership | Event payload only |
Bundled templates
The package ships plain, unbranded HTML under . Use them as-is or copy them into your and redesign.
| Template file | Good starting point for |
|---|---|
| Alternate order confirmation | |
| Returns / refunds | |
| Email confirmation flows | |
| Account removal | |
| / | Loyalty custom events |
| / | Wallet custom events |
| Membership custom event | |
| / | Free-form messages |
Brand with and optional . Regenerate the defaults from the plugin repo with:
Suggested mapping examples
Order confirmation
-
Event:
-
Template:
-
Subject:
-
Recipient: Order email
-
Variables:
Name Path
Shipment
-
Event:
-
Template:
-
Subject:
-
Variables:
Name Path
Test the Plugin
-
Run your Medusa backend:
-
Open Admin → Mailer and check that SMTP shows as configured.
-
Create an active mapping for → (or your own template).
-
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.
-
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 ).
Admin API (optional)
Useful for automation or custom UIs. All routes require an authenticated admin user.
| Method | Path | Purpose |
|---|---|---|
| SMTP status and sender profiles | ||
| Template files and detected variables | ||
| List mappings | ||
| Create mapping | ||
| Update mapping | ||
| Delete mapping | ||
| Manual / test send |
You can also trigger the same pipeline from code:
Troubleshooting
| What you see | What to check |
|---|---|
| No emails ever | SMTP env incomplete; Admin still says not configured |
| Event fires, no email | No active mapping for that exact event name |
| Shipment email never sends | Map , not only older fulfillment aliases |
| Empty fields in the body | Variable path wrong for that event’s data shape |
| Wrong “to” address | Guest orders use order email; adjust recipient type |
| Two emails for one action | Another subscriber in your app is also sending — turn one off |
Develop this repository
Peer dependencies should match your host Medusa version as closely as practical.
Additional Resources
License
MIT

