SMTP Notification Provider

A robust SMTP email notification provider for MedusaJS, enabling reliable email delivery through any SMTP service provider for transactional and marketing emails.

Overview

This plugin integrates SMTP email functionality into your MedusaJS store using Nodemailer. It supports any SMTP service provider including Gmail, SendGrid, Mailgun, and custom SMTP servers, providing a flexible solution for email communications.

Features

• SMTP Integration - Connect to any SMTP email service provider
• Transactional Emails - Send order confirmations, shipping updates, and receipts
• Marketing Emails - Newsletter and promotional email support
• Multiple Provider Support - Works with Gmail, SendGrid, Mailgun, and more
• Secure Connection - SSL/TLS encryption support
• Easy Configuration - Simple environment variable setup
• Nodemailer Powered - Built on the reliable Nodemailer library
• MedusaJS v2 Compatible - Built for Medusa v2.5.0 and later

Requirements

• MedusaJS v2.5.0 or later
• Node.js (latest LTS recommended)
• SMTP service provider account (Gmail, SendGrid, etc.)
• Nodemailer package

Installation

Install the plugin and nodemailer:

npm install @tsc_tech/medusa-plugin-smtp nodemailer

Configuration

Step 1: Choose SMTP Provider

Select an SMTP service provider:

• Gmail - Free tier available, good for development
• SendGrid - Professional email delivery
• Mailgun - Transactional email service
• Amazon SES - Scalable email service
• Custom SMTP - Any SMTP server

Step 2: Get SMTP Credentials

Obtain credentials from your provider:

Gmail Example:

• Host: smtp.gmail.com
• Port: 587 (TLS) or 465 (SSL)
• Username: Your Gmail address
• Password: App-specific password (not your Gmail password)

SendGrid Example:

• Host: smtp.sendgrid.net
• Port: 587 or 465
• Username: apikey
• Password: Your SendGrid API key

Step 3: Environment Variables

Add your SMTP credentials to .env:

# SMTP Server Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true  # true for 465, false for other ports

# SMTP Authentication
SMTP_AUTH_USER=your-email@gmail.com
SMTP_AUTH_PASS=your-app-password

# Email Settings
SMTP_NAME=YourStoreName
SMTP_FROM=your-email@gmail.com
DEFAULT_REPLY_TO=support@yourstore.com

Step 4: Plugin Configuration

Add the plugin to your medusa-config.ts:

import { Modules } from "@medusajs/framework/utils"

module.exports = defineConfig({
  // ... other config
  modules: {
    [Modules.NOTIFICATION]: {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          {
            resolve: "@tsc_tech/medusa-plugin-smtp",
            id: "smtp",
            options: {
              channels: ["email"],
              transport: {
                host: process.env.SMTP_HOST,
                port: process.env.SMTP_PORT,
                secure: process.env.SMTP_SECURE === "true",
                auth: {
                  user: process.env.SMTP_AUTH_USER,
                  pass: process.env.SMTP_AUTH_PASS,
                },
              },
              from: process.env.SMTP_FROM,
              name: process.env.SMTP_NAME,
              reply_to: process.env.DEFAULT_REPLY_TO,
            },
          },
        ],
      },
    },
  },
})

Usage

Sending Emails

Use the notification service to send emails:

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const notificationModuleService = req.scope.resolve("notification")

  await notificationModuleService.createNotifications({
    to: "customer@example.com",
    channel: "email",
    template: "order-placed",
    data: {
      // Email data
      subject: "Order Confirmation",
      // ... other template data
    },
  })

  res.json({ success: true })
}

Email Types

Common email notifications:

• Order Confirmation - Send when orders are placed
• Shipping Notification - Notify customers of shipment
• Delivery Confirmation - Confirm successful delivery
• Password Reset - Send password reset links
• Account Creation - Welcome new customers
• Abandoned Cart - Remind about incomplete purchases
• Order Updates - Status changes and updates

SMTP Provider Setup Guides

Gmail Configuration

1. Enable 2-factor authentication on your Google account
2. Generate an app-specific password:
   • Go to Google Account Settings
   • Security → App passwords
   • Create a new app password
3. Use app password in SMTP_AUTH_PASS

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_AUTH_USER=youremail@gmail.com
SMTP_AUTH_PASS=your-16-digit-app-password

SendGrid Configuration

1. Create SendGrid account and verify sender
2. Generate API key from Settings → API Keys
3. Use API key as password:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_AUTH_USER=apikey
SMTP_AUTH_PASS=your-sendgrid-api-key

Mailgun Configuration

1. Add and verify your domain in Mailgun
2. Get SMTP credentials from domain settings:

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_SECURE=false
SMTP_AUTH_USER=postmaster@your-domain.com
SMTP_AUTH_PASS=your-mailgun-smtp-password

Port Configuration

Common SMTP ports:

• Port 25 - Standard SMTP (often blocked by ISPs)
• Port 587 - SMTP with STARTTLS (recommended)
• Port 465 - SMTP with SSL (secure)
• Port 2525 - Alternative port for STARTTLS

Use SMTP_SECURE=true for port 465, false for others.

Email Templates

Create email templates for different events:

// templates/order-placed.tsx
export default function OrderPlaced({ order }) {
  return (
    <html>
      <body>
        <h1>Order Confirmation</h1>
        <p>Thank you for your order #{order.display_id}</p>
        {/* ... email content */}
      </body>
    </html>
  )
}

Testing

Development Testing

For development, you can use:

• Gmail - Free and easy to set up
• Mailtrap - Email testing service
• Ethereal - Fake SMTP service for testing

Test Configuration

# Mailtrap example
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_SECURE=false
SMTP_AUTH_USER=your-mailtrap-username
SMTP_AUTH_PASS=your-mailtrap-password

Troubleshooting

Common Issues

Authentication Failed:

• Verify username and password
• Check if 2FA is enabled (use app password)
• Ensure credentials are correct in .env

Connection Timeout:

• Check SMTP host and port
• Verify firewall settings
• Try alternative port (2525)

Emails Not Sending:

• Check email provider limits
• Verify sender email is authorized
• Review email provider logs

Best Practices

1. Use App Passwords - Never use your main account password
2. SSL/TLS - Always use secure connections
3. Sender Verification - Verify your sending domain
4. Rate Limits - Be aware of provider sending limits
5. Error Handling - Implement proper error handling
6. Email Validation - Validate recipient email addresses
7. Unsubscribe - Include unsubscribe links for marketing emails

Links

• Nodemailer Documentation
• SMTP Protocol