Nodemailer Gmail Plugin

What is Nodemailer Gmail Plugin

The @simplens/nodemailer-gmail plugin enables email delivery through Gmail SMTP using the popular Nodemailer library.

How It Works

This plugin creates a Nodemailer transporter configured for Gmail's SMTP servers. When a notification is sent:

The plugin receives the notification payload
Replaces any {{variable}} placeholders in the message
Auto-detects if the message is HTML or plain text
Sends the email via Gmail SMTP

Gmail has sending limits: ~500 emails/day for regular accounts and ~2,000/day for Google Workspace.

Installation

npm run plugin:install @simplens/nodemailer-gmail

See the Plugin Installation Guide for installing plugins in your simplens-core

Configuration

Add the plugin to your simplens.config.yaml if you used Config-first method from Plugin Instattion Guide:

simplens.config.yaml

providers:
  - package: "@simplens/nodemailer-gmail"
    id: nodemailer-gmail
    credentials:
      EMAIL_USER: ${EMAIL_USER}
      EMAIL_PASS: ${EMAIL_PASS}
    optionalConfig: #Optional
      EMAIL_HOST: ${EMAIL_HOST} 
      EMAIL_PORT: ${EMAIL_PORT}
      EMAIL_FROM: ${EMAIL_FROM}
    options:
      priority: 1
      rateLimit:
        maxTokens: 100
        refillRate: 10

channels:
  email:
    default: "nodemailer-gmail"

Required Credentials

Key	Description
`EMAIL_USER`	Your Gmail address
`EMAIL_PASS`	Gmail App Password (not regular password)

Optional Config

Key	Default	Description
`EMAIL_HOST`	`smtp.gmail.com`	SMTP host
`EMAIL_PORT`	`587`	SMTP port (use `465` for SSL)
`EMAIL_FROM`	`EMAIL_USER`	Sender email address

Rate Limit

Key	Default	Description
`maxTokens`	`100`	Max tokens in bucket
`refillRate`	`10`	Tokens refilled per second (~100/min max)

Gmail App Password Setup

You cannot use your regular Gmail password. You must generate an App Password.

Enable 2-Factor Authentication

Go to your Google Account security settings and enable 2FA.

Generate App Password

Navigate to App Passwords and create a new password for "Mail".

Use the App Password

Set EMAIL_PASS to the generated 16-character password.

Environment Variables

.env

EMAIL_USER=your-email@gmail.com
EMAIL_PASS=xxxx-xxxx-xxxx-xxxx
EMAIL_FROM=your-email@gmail.com  # Optional
EMAIL_HOST=smtp.gmail.com        # Optional
EMAIL_PORT=587                   # Optional

Notification Payload

You can easily get and configure this request payload from Payload Studio in Admin Dashboard

{
  "request_id": "uuid-v4",
  "client_id": "uuid-v4",
  "channel": "email",
  "recipient": {
    "user_id": "user-123",
    "email": "recipient@example.com"
  },
  "content": {
    "subject": "Welcome!",
    "message": "Hello {{name}}, your order #{{order_id}} is confirmed."
  },
  "variables": {
    "name": "John",
    "order_id": "12345"
  }
}

Features

Feature	Description
HTML & Plain Text	Auto-detects content type
Template Variables	Supports `{{key}}` syntax
Rate Limiting	Configurable token bucket
Smart Retry	Classifies errors as retryable or non-retryable
Any SMTP Server	Works with Gmail or any SMTP provider

Nodemailer Gmail Plugin

On this page