Notification mailgun

Sends transactional emails via the Mailgun HTTP API. Supports stored templates (with localization), inline HTML/text, file attachments, and includes an Admin UI page for sending test emails and verifying event coverage.

Requires MedusaJS v2.3.0 or later.

In a hurry? Quickstart! From install to first email in ~15 minutes.

What this plugin provides

• Notification provider — registers mailgun as a notification provider for the email channel. Called automatically by Medusa when you use createNotifications() in a subscriber.
• Admin API: send test email — POST /admin/mailgun/send-email. Sends a test email to a registered admin user.
• Admin API: event checklist — GET /admin/mailgun/checklist. Scans your subscribers and Mailgun account to report coverage status for each tracked event.
• Admin UI — a "Mailgun" page in the Medusa admin sidebar with two tabs: "Event Checklist" (default) and "Send Test".

Prerequisites

• Node.js v20+
• MedusaJS v2.3.0+
• A Mailgun account with a verified sending domain

Installation

1pnpm add @mdgar/medusa-notification-mailgun
2# or
3npm install @mdgar/medusa-notification-mailgun
4# or
5yarn add @mdgar/medusa-notification-mailgun

mailgun.js is bundled as a direct dependency of the plugin and will be installed automatically; you do not need to install it separately.

Configuration

Add the plugin to medusa-config.ts. Two entries are needed: a plugins entry to load the admin UI and API routes, and a modules entry to register the notification provider.

1import { defineConfig } from "@medusajs/framework/utils"
2
3module.exports = defineConfig({
4  // ...
5  plugins: [
6    "@mdgar/medusa-notification-mailgun",
7  ],
8  modules: [
9    {
10      resolve: "@medusajs/medusa/notification",
11      options: {
12        providers: [
13          {
14            resolve: "@mdgar/medusa-notification-mailgun/providers/notification-mailgun",
15            id: "mailgun",
16            options: {
17              channels: ["email"],
18              api_key: process.env.MAILGUN_API_KEY,
19              domain: process.env.MAILGUN_DOMAIN,
20              from: process.env.MAILGUN_FROM,  // optional
21              region: "us",                     // optional, "us" | "eu"
22            },
23          },
24        ],
25      },
26    },
27  ],
28})

Options

Customizing the checklist event map

The admin "Event Checklist" tab scans your subscribers against a built-in list of Medusa events and their expected Mailgun template names (e.g. order.placed → order-confirmation). To add your own events or rename an expected template, pass eventMap in the provider options:

1{
2  resolve: "@mdgar/medusa-notification-mailgun/providers/notification-mailgun",
3  id: "mailgun",
4  options: {
5    channels: ["email"],
6    api_key: process.env.MAILGUN_API_KEY,
7    domain: process.env.MAILGUN_DOMAIN,
8    eventMap: [
9      // Override a built-in: use a different template name for order.placed
10      { event: "order.placed", expected_template: "my-order-confirmation" },
11      // Append a custom event
12      { event: "loyalty.tier_upgraded", expected_template: "loyalty-upgrade" },
13    ],
14  },
15}

Each entry is { event: string; expected_template: string }. The checklist endpoint merges your overrides onto the built-in map by event key.

Environment variables

Set these in your .env file:

1MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
2MAILGUN_DOMAIN=mg.yourdomain.com
3MAILGUN_FROM=no-reply@yourdomain.com
4# MAILGUN_REGION=eu  # uncomment if your account is on the EU region

Reference these in medusa-config.ts via process.env — the checklist endpoint reads credentials from the same plugin options object, not from the environment directly.

Sending notifications

The provider integrates with Medusa's built-in notification system. Call createNotifications() from a subscriber or workflow:

1const notificationService = container.resolve(Modules.NOTIFICATION)
2
3await notificationService.createNotifications({
4  to: "customer@example.com",
5  channel: "email",
6  template: "order-confirmation",
7  data: {
8    subject: "Your order is confirmed",
9    order_id: "ord_123",
10    customer_name: "Alice",
11  },
12})

The data payload

The data object controls how the email is built and carries template variables. All values must be strings.

Content selection

The provider selects the message body using this priority order:

1. template — a Mailgun stored template; all data fields are passed as h:X-Mailgun-Variables.
2. data.html — raw HTML body (no template).
3. data.text — plain-text body.

If none of template, data.html, or data.text is provided, the provider throws INVALID_DATA rather than sending an email with a serialized DTO body.

Use data.html or data.text when you want to generate content dynamically in code rather than maintain a template in the Mailgun dashboard.

Stored template

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  template: "order-confirmation",
5  data: {
6    subject: "Your order is confirmed",
7    order_id: "ord_123",
8  },
9})

Template variables are forwarded to Mailgun via h:X-Mailgun-Variables and available as {{variable_name}} inside Mailgun's Handlebars templates.

Localized template

Create multiple versions of a template in the Mailgun dashboard, tagging each with a locale (e.g. en, fr, de). Pass locale in data to select the matching version:

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  template: "order-confirmation",
5  data: {
6    locale: "fr",
7    subject: "Votre commande est confirmée",
8    order_id: "ord_123",
9  },
10})

When locale is present, the plugin sets Mailgun's t:version parameter. If omitted, Mailgun uses the template's default version.

Inline HTML

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  data: {
5    subject: "Welcome!",
6    html: "<h1>Welcome to our store</h1><p>Thanks for signing up.</p>",
7  },
8})

Plain text

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  data: {
5    subject: "Your receipt",
6    text: "Thanks for your order. Your total was $42.00.",
7  },
8})

Attachments

Pass base64-encoded file content in the attachments field:

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  data: { subject: "Your invoice", text: "See attached." },
5  attachments: [
6    {
7      filename: "invoice.pdf",
8      content: "<base64-encoded content>",
9    },
10  ],
11} as any)

Overriding the sender address

Pass a from field on the notification to override the plugin-level default for a single send:

1await notificationService.createNotifications({
2  to: "customer@example.com",
3  channel: "email",
4  from: "billing@yourdomain.com",
5  data: { subject: "Invoice", text: "..." },
6} as any)

data.from is also accepted, but is ignored when the top-level notification from field is set. Resolution order is: top-level from → data.from → plugin-level default from → noreply@<domain>. The top-level from field shown above is the preferred method.

Wiring up Medusa events to templates

Medusa fires events for commerce operations (order placed, shipment created, password reset, etc.) but sends no email by default. To send email on an event you need a Mailgun template and a subscriber that calls createNotifications() when the event fires.

See docs/medusa-notification-events.md for the complete how-to guide: subscriber patterns for each event, the full event reference, and suggested template variables.

New to the plugin? The quickstart walks through the full setup end-to-end.

Admin UI

The plugin adds a Mailgun page to the Medusa admin sidebar (envelope icon). The route is /mailgun.

The page has two tabs:

• Event Checklist (default) — runs GET /admin/mailgun/checklist and displays per-event status as a table. Shows whether each tracked event has a subscriber, what template name was detected in the subscriber, and whether that template exists in Mailgun. For events with a confirmed Mailgun template, the template name is displayed below the event name in the table row.

• Send Test — form to send a test email to a registered admin user. Fields: recipient (dropdown of admin users), subject, optional message body, optional template name, optional from-address override, optional reply-to address, and optional key-value template variables.

Admin API: send test email

1POST /admin/mailgun/send-email
2Authorization: Bearer <admin-jwt>
3Content-Type: application/json

Sends a test email through the Mailgun notification provider.

Request body

Constraint: to must be the email address of a registered Medusa admin user. The endpoint looks up the address in the user service before sending. Arbitrary addresses are rejected.

If no template is specified and data contains neither html nor text, the plugin sends a plain-text fallback: Test email — subject: <subject> (or just Test email if no subject is provided).

Response

{ "success": true, "notification_id": "noti_01..." }

Example

1curl -X POST https://yourstore.com/admin/mailgun/send-email \
2  -H "Authorization: Bearer <admin-jwt>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "to": "admin@yourstore.com",
6    "subject": "Hello from Mailgun",
7    "template": "welcome",
8    "data": { "customer_name": "Alice" }
9  }'

Admin API: event checklist

1GET /admin/mailgun/checklist
2Authorization: Bearer <admin-jwt>

Returns a diagnostic report for all tracked Medusa events. For each event, the endpoint checks:

1. Whether a subscriber file exists in src/subscribers/ that references the event name.
2. Whether that subscriber file contains a static template: string literal, and what its value is.
3. Whether that template exists in your Mailgun account (requires api_key and domain to be set in the plugin options in medusa-config.ts).

Per-event status values:

The top-level status rolls up the worst result across all events, excluding inline. inline events do not cause a warn or fail rollup.

CI usage

1# Fail if any event is missing a subscriber or Mailgun template
2curl -sf -H "Authorization: Bearer $MEDUSA_ADMIN_TOKEN" \
3  "$MEDUSA_BACKEND_URL/admin/mailgun/checklist" \
4  | jq -e '.status == "pass"'
5
6# Fail only if a subscriber is missing; allow missing templates
7curl -sf -H "Authorization: Bearer $MEDUSA_ADMIN_TOKEN" \
8  "$MEDUSA_BACKEND_URL/admin/mailgun/checklist" \
9  | jq -e '.status != "fail"'

See docs/checklist-endpoint.md for the full response shape, field descriptions, and additional CI patterns.

Development

1# Install dependencies
2pnpm install
3
4# Build the plugin
5pnpm run build
6
7# Start in watch/develop mode
8pnpm run dev
9
10# Run tests
11pnpm test

This plugin uses the official Medusa plugin toolchain (medusa plugin:build / medusa plugin:develop).

Local development with pnpm link

To test the plugin in a local Medusa project before publishing:

1# In this plugin directory — build first, then link
2pnpm run build
3pnpm link --global
4
5# In your Medusa project
6pnpm link --global @mdgar/medusa-notification-mailgun

After any source change, run pnpm run build in the plugin directory again, or keep pnpm run dev running to rebuild continuously.

Tests

The test suite uses Jest and ts-jest. Run with:

pnpm test

Coverage includes:

• validateOptions — rejects missing api_key or domain
• Template path — h:X-Mailgun-Variables header, t:version locale selection
• Inline HTML and plain-text paths
• Sender resolution — configured address vs. noreply@<domain> default
• Subject omitted from payload when data.subject is absent (defers to template subject)
• Base64 attachment decoding
• Mailgun API errors are wrapped in MedusaError with a sanitized, correlation-id'd message (Mailgun send failed (ref: mg_…)); raw error details are logged server-side only. INVALID_DATA validation errors are re-thrown unwrapped.
• EU region endpoint selection (https://api.eu.mailgun.net)
• Return value — id field with message field fallback

License

MIT