Features

• ✅ Plunk Email Provider - Seamless integration with Plunk for email delivery
• ✅ 12 Medusa Core Subscribers - Ready-to-use notifications for orders, customers, fulfillment, and returns
• ✅ 18 MercurJS Marketplace Subscribers - Seller, product, and payout notifications (⚠️ testing phase)
• ✅ Template-Based System - Easy-to-customize email templates via Plunk dashboard
• ✅ Type-Safe - Full TypeScript support
• ✅ Medusa v2 Compatible - Built for Medusa v2.4.0+

Installation

npm install @erulabs-tech/medusa-plugin-email
# or
pnpm add @erulabs-tech/medusa-plugin-email
# or
yarn add @erulabs-tech/medusa-plugin-email

Configuration

1. Environment Variables

Create or update your .env file:

# Plunk Configuration
PLUNK_API_KEY=pk_...your_api_key
[email protected]
PLUNK_FROM_NAME=Your Store Name

2. Plugin Registration

Add the plugin to your medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils";

export default defineConfig({
  // ... other config
  plugins: [
    {
      resolve: "@erulabs-tech/medusa-plugin-email",
      options: {
        // Plugin options if needed
      },
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          {
            resolve: "@erulabs-tech/medusa-plugin-email/providers/use-plunk",
            id: "use-plunk",
            options: {
              apiKey: process.env.PLUNK_API_KEY,
              from: process.env.PLUNK_FROM_EMAIL,
              fromName: process.env.PLUNK_FROM_NAME,
              channels: ["email"],
            },
          },
        ],
      },
    },
  ],
});

Available Email Notifications

Medusa Core Events (Stable ✅)

These subscribers are production-ready and handle standard Medusa commerce events.

| Event | Template | Description | |-------|----------|-------------| | customer.created | welcomeUser | Welcome email when new customer registers | | customer.updated | customerUpdated | Profile update confirmation | | order.placed | orderPlaced | Order confirmation with items and totals | | order.completed | orderCompleted | Order completion + review request | | order.canceled | orderCanceled | Cancellation notice with refund info | | fulfillment.created | fulfillmentCreated | Order processing started | | fulfillment.shipment_created | fulfillmentShipmentCreated | Shipping confirmation with tracking | | fulfillment.delivery_created | fulfillmentDeliveryCreated | Delivery confirmation | | return.created | returnCreated | Return request confirmation | | return.received | returnReceived | Refund processing notice | | claim.created | claimCreated | Claim acknowledgment | | exchange.created | exchangeCreated | Exchange confirmation |

MercurJS Marketplace Events (⚠️ Testing Phase)

These subscribers integrate with the MercurJS marketplace module. They are currently in testing and should be validated in your environment before production use.

Seller Account Notifications

| Event | Template | Description | |-------|----------|-------------| | requests.seller.draft | requestsSellerDraft | Account created (draft status) | | requests.seller.created | requestsSellerCreated | Application submitted | | requests.seller.pending | requestsSellerPending | Under review notice | | requests.seller.accepted | requestsSellerAccepted | Welcome seller - account approved | | requests.seller.rejected | requestsSellerRejected | Application rejected with reason | | seller.store_status_changed | sellerStoreStatus* | Store status change (active/inactive/suspended) | | seller.team.invite.created | sellerTeamInviteCreated | Team member invitation |

Product Request Notifications

| Event | Template | Description | |-------|----------|-------------| | requests.product.created | requestsProductCreated | Product submission confirmation | | requests.product.pending | requestsProductPending | Product under review | | requests.product.accepted | requestsProductAccepted | Product approved for sale | | requests.product.rejected | requestsProductRejected | Product rejected - needs changes | | requests.product_update.created | requestsProductUpdateCreated | Update submission confirmation | | requests.product_update.pending | requestsProductUpdatePending | Update under review | | requests.product_update.accepted | requestsProductUpdateAccepted | Update approved | | requests.product_update.rejected | requestsProductUpdateRejected | Update rejected - needs changes |

Payout Notifications

| Event | Template | Description | |-------|----------|-------------| | payout.succeeded | payoutSucceeded | Payout processed successfully | | payout.failed | payoutFailed | Payout failure - action required |

Order Notifications

| Event | Template | Description | |-------|----------|-------------| | order.canceled | orderCanceled | Order cancellation (MercurJS vendor orders) | | order_set.placed | orderSetPlaced | Multi-seller order confirmation |

Plunk Template Setup

Creating Templates

1. Log in to your Plunk dashboard
2. Navigate to Templates → Create Template
3. Create templates with the exact names listed above
4. Use the following variables in your templates:

Template Variables Reference

welcomeUser

{
  "name": "Customer full name",
  "email": "Customer email"
}

orderPlaced

{
  "name": "Customer full name",
  "order_id": "Order display ID",
  "order_date": "Order date",
  "items": "Array of order items",
  "subtotal": "Order subtotal",
  "total": "Order total",
  "shipping_address": "Shipping address object"
}

orderCompleted

{
  "name": "Customer full name",
  "order_id": "Order display ID",
  "completion_date": "Completion date",
  "items": "Array of order items",
  "total": "Order total"
}

orderCanceled

{
  "name": "Customer full name",
  "order_id": "Order display ID",
  "cancellation_date": "Cancellation date",
  "items": "Array of order items",
  "total": "Order total",
  "refund_amount": "Refund amount"
}

fulfillmentShipmentCreated

{
  "name": "Customer full name",
  "order_id": "Order display ID",
  "shipment_date": "Shipment date",
  "tracking_numbers": "Array of tracking numbers",
  "tracking_url": "Tracking URL",
  "shipping_address": "Shipping address object",
  "items": "Array of order items"
}

returnCreated / returnReceived

{
  "name": "Customer full name",
  "order_id": "Order display ID",
  "return_id": "Return display ID",
  "request_date": "Request/received date",
  "items": "Array of return items",
  "refund_amount": "Refund amount",
  "reason": "Return reason"
}

requestsSellerAccepted

{
  "name": "Seller full name",
  "store_name": "Store name",
  "approval_date": "Approval date"
}

payoutSucceeded / payoutFailed

{
  "name": "Seller full name",
  "store_name": "Store name",
  "amount": "Payout amount (in cents)",
  "currency": "Currency code",
  "payout_date": "Payout date",
  "order_id": "Related order ID"
}

requestsProductAccepted / requestsProductRejected

{
  "name": "Seller full name",
  "store_name": "Store name",
  "product_name": "Product title",
  "approval_date": "Approval/rejection date",
  "reason": "Rejection reason (if applicable)"
}

Development

Running in Development

# Clone the repository
cd packages/email

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

Building the Plugin

pnpm build

Local Testing with yalc

# Build and publish locally
pnpm build
yalc publish

# In your Medusa project
yalc add @erulabs-tech/medusa-plugin-email

Plugin Architecture

src/
├── admin/                    # Admin UI customizations
│   └── i18n/
├── api/                      # Custom API routes
│   ├── admin/
│   └── store/
├── subscribers/
│   ├── medusa/               # Core Medusa events (✅ Stable)
│   │   ├── customer-created.ts
│   │   ├── customer-updated.ts
│   │   ├── order-placed.ts
│   │   ├── order-completed.ts
│   │   ├── order-canceled.ts
│   │   ├── fulfillment-*.ts
│   │   ├── return-*.ts
│   │   ├── claim-created.ts
│   │   └── exchange-created.ts
│   └── mercurjs/             # MercurJS events (⚠️ Testing)
│       ├── requests-seller-*.ts
│       ├── requests-product-*.ts
│       ├── payout-*.ts
│       ├── seller-*.ts
│       └── order-*.ts
├── providers/
│   └── use-plunk/            # Plunk notification provider
│       ├── index.ts
│       ├── service.ts
│       └── templates/
├── workflows/
│   └── steps/
└── links/

Planned Features 🚧

The following features are planned for future releases:

• [ ] Admin UI - Email template management dashboard within Medusa Admin
• [ ] Email Analytics - Delivery tracking, open rates, click tracking
• [ ] Batch Notifications - Bulk email sending for promotions
• [ ] Email Preferences - Customer subscription/unsubscription management
• [ ] Additional Providers - SendGrid, Resend, AWS SES support
• [ ] Cart Abandonment - Automated cart recovery emails
• [ ] Review Requests - Post-purchase product review emails
• [ ] Back in Stock - Inventory notification alerts
• [ ] Price Alerts - Price drop notifications for wishlisted items
• [ ] Email Scheduling - Delayed/scheduled email sending
• [ ] A/B Testing - Template performance testing
• [ ] Multi-language - i18n support for email templates

Known Limitations

• MercurJS Dependency: MercurJS subscribers require the MercurJS marketplace module to be installed
• Manual Template Setup: Email templates must be created manually in the Plunk dashboard
• No Queue Management: Built-in email queue management is not included (relies on Medusa's job system)
• Testing Required: MercurJS subscribers should be thoroughly tested in your environment before production use

Troubleshooting

Emails Not Sending

1. Verify PLUNK_API_KEY is correct in your .env
2. Check that templates exist in Plunk with exact names
3. Ensure the notification module is properly configured
4. Check Medusa logs for error messages

Template Variables Not Rendering

1. Verify variable names match exactly (case-sensitive)
2. Check that the subscriber is passing the correct data structure
3. Test with simple text templates first

MercurJS Events Not Triggering

1. Ensure MercurJS marketplace module is installed
2. Verify MercurJS version compatibility
3. Check that request entities are being created properly
4. Review Medusa logs for event emission

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code patterns
• Add TypeScript types for all new code
• Include JSDoc comments for public APIs
• Test subscribers with real events before submitting

License

Distributed under the MIT License. See LICENSE for more information.

Support & Links

• 📚 Medusa Documentation
• 📦 npm Package
• 💬 Discord Community
• 🐛 Issue Tracker
• 🐦 Twitter

Acknowledgments

• Built with Medusa v2
• Email delivery powered by Plunk
• Marketplace events from MercurJS