Mailer

@sam-ael/medusa-plugin-mailer

Production-focused email notification plugin for Medusa v2 with event mapping, template rendering, and admin-managed delivery flows.

Highlights

• Admin-managed event -> template mappings
• Template variable mapping with safe path resolution
• SMTP-based delivery with sender profile support
• Workflow-driven event delivery for worker deployments
• Hardened API responses and stricter payload validation
• POST /admin/mailer/mappings/:id as the primary update endpoint
• Temporary deprecated PUT compatibility with deprecation headers

Install

yarn add @sam-ael/medusa-plugin-mailer nodemailer

Medusa Configuration

1plugins: [
2  {
3    resolve: "@sam-ael/medusa-plugin-mailer",
4    options: {},
5  },
6]

Environment Variables

1MAILER_SMTP_HOST=smtp.gmail.com
2MAILER_SMTP_PORT=587
3MAILER_SMTP_USER=your-email@example.com
4MAILER_SMTP_PASS=your-app-password
5MAILER_SMTP_SECURE=false
6
7MAILER_FROM_NAME_1=My Store
8MAILER_FROM_ADDRESS_1=no-reply@mystore.com
9
10MAILER_TEMPLATES_DIR=src/email_templates
11MAILER_SEND_CONCURRENCY=2

Admin API

Security and Reliability Notes

• Unified error contract: { success: false, code, message, details? }
• Recipient and payload validation at route level
• Mapping updates use direct update flow (no delete/recreate pattern)
• Event-send workflow uses bounded concurrency and per-item failure isolation
• Indexes added for high-frequency lookup fields

Quality Gates

1yarn typecheck
2yarn lint
3yarn test
4yarn build

Smoke tests are available under src/tests.

License

MIT