Nodemailer (SMTP)

Overview

Nodemailer is a flexible SMTP client that allows you to send emails through any SMTP server. Use Nodemailer when you:

Have an existing SMTP server
Use a provider not natively supported (Gmail, SendGrid SMTP, Amazon SES, etc.)
Need full control over email transport
Want to use your company’s email infrastructure
Need to send emails through custom mail servers

Nodemailer is the third provider ShipFree checks during auto-discovery. It will be used if Resend and Postmark aren’t configured.

Prerequisites

Access to an SMTP server
SMTP credentials (host, port, username, password)

Setup Instructions

Step 1: Gather SMTP Credentials

You’ll need the following from your email provider:

SMTP Host - Server address (e.g., smtp.gmail.com)
SMTP Port - Usually 587 (STARTTLS) or 465 (TLS/SSL)
Username - Your email address or SMTP username
Password - Your email password or app-specific password
Secure - true for port 465, false for port 587

For Gmail and other providers with 2FA, you’ll need an app-specific password, not your regular account password.

Step 2: Configure Environment Variables

Add these to your .env file:

# Required
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-password-or-app-password

# Optional - "true" for TLS/SSL (port 465), "false" for STARTTLS (port 587)
SMTP_SECURE=false

# Optional - explicitly set Nodemailer as provider
EMAIL_PROVIDER=nodemailer

# Email defaults
DEFAULT_FROM_EMAIL=noreply@yourdomain.com
DEFAULT_FROM_NAME=Your App Name

Step 3: Install Nodemailer

Nodemailer is already included in ShipFree:

// package.json (already installed)
"nodemailer": "^7.0.12",
"@types/nodemailer": "^7.0.4"

If you need to reinstall:

bun add nodemailer
bun add -D @types/nodemailer

Step 4: Test Your Configuration

import { sendEmail, getActiveProviderName } from '@/lib/messaging/email';

// Verify Nodemailer is active
console.log('Active provider:', getActiveProviderName()); // Should output: 'nodemailer'

// Send test email
const result = await sendEmail({
  to: 'test@example.com',
  subject: 'Test from ShipFree via Nodemailer',
  html: '<h1>Success!</h1><p>SMTP is configured correctly.</p>',
});

if (result.success) {
  console.log('Email sent via SMTP!', result.data);
} else {
  console.error('Failed:', result.message);
}

Common SMTP Providers

Gmail

Setup:

Enable 2-factor authentication on your Google account
Go to Google Account → Security → App passwords
Create a new app password for “Mail”
Use the generated password (not your account password)

Configuration:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-specific-password
SMTP_SECURE=false

Gmail has a sending limit of 500 emails/day for free accounts and 2,000/day for Google Workspace.

Amazon SES

Setup:

Sign up for Amazon SES
Verify your domain or email address
Create SMTP credentials in the SES console
Note your SMTP endpoint (region-specific)

Configuration:

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-username
SMTP_PASS=your-ses-smtp-password
SMTP_SECURE=false

SES starts in sandbox mode. Request production access to send to any email address.

SendGrid SMTP

Setup:

Create a SendGrid account
Go to Settings → API Keys
Create an API key with “Mail Send” permissions
Use “apikey” as username and the API key as password

Configuration:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key
SMTP_SECURE=false

Microsoft 365 / Outlook

Setup:

Ensure SMTP authentication is enabled for your account
Use your Microsoft 365 email and password
May require app password if 2FA is enabled

Configuration:

SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_USER=your-email@company.com
SMTP_PASS=your-password
SMTP_SECURE=false

Mailgun SMTP

Setup:

Create a Mailgun account
Verify your domain
Get SMTP credentials from Mailgun dashboard

Configuration:

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@yourdomain.com
SMTP_PASS=your-mailgun-password
SMTP_SECURE=false

Custom/Self-Hosted SMTP

Configuration:

SMTP_HOST=mail.yourdomain.com
SMTP_PORT=587  # or 465 for SSL
SMTP_USER=smtp-username
SMTP_PASS=smtp-password
SMTP_SECURE=false  # or true for port 465

Contact your hosting provider or IT department for SMTP server details.

Features

Email Attachments

Nodemailer has excellent attachment support:

import { sendEmail } from '@/lib/messaging/email';
import { readFileSync } from 'fs';

await sendEmail({
  to: 'user@example.com',
  subject: 'Invoice #1234',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: readFileSync('./invoice.pdf'),
      contentType: 'application/pdf',
    },
    {
      filename: 'logo.png',
      content: readFileSync('./logo.png'),
      contentType: 'image/png',
      disposition: 'inline', // Embed in email
    },
  ],
});

Custom Headers

Full control over email headers:

await sendEmail({
  to: 'user@example.com',
  subject: 'Newsletter',
  html: '<p>Monthly update</p>',
  emailType: 'marketing',
  includeUnsubscribe: true,
  unsubscribeInfo: {
    baseUrl: 'https://yourdomain.com',
    token: 'user-token',
    writerId: 'newsletter',
  },
});

Reply-To Address

await sendEmail({
  to: 'customer@example.com',
  subject: 'Support Request',
  html: '<p>Your ticket has been created.</p>',
  replyTo: 'support@yourdomain.com',
});

Plain Text Alternative

await sendEmail({
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<h1>Welcome!</h1><p>Thanks for joining.</p>',
  text: 'Welcome!\n\nThanks for joining.',
});

Batch Email Sending

Nodemailer sends batch emails sequentially:

import { sendBatchEmails } from '@/lib/messaging/email';

await sendBatchEmails({
  emails: [
    { to: 'user1@example.com', subject: 'Hi', html: '<p>Hello</p>' },
    { to: 'user2@example.com', subject: 'Hi', html: '<p>Hello</p>' },
  ],
});

While functional, batch sending via SMTP is slower than providers with native batch APIs (like Resend or Postmark).

Environment Variables Reference

Variable	Required	Description	Example
`SMTP_HOST`	Yes	SMTP server hostname	`smtp.gmail.com`
`SMTP_PORT`	Yes	SMTP server port	`587` or `465`
`SMTP_USER`	Yes	SMTP username/email	`user@example.com`
`SMTP_PASS`	Yes	SMTP password	`your-password`
`SMTP_SECURE`	No	Use TLS/SSL (`true` for 465, `false` for 587)	`false`
`EMAIL_PROVIDER`	No	Force Nodemailer as provider	`nodemailer`
`DEFAULT_FROM_EMAIL`	No	Default sender email	`noreply@yourdomain.com`
`DEFAULT_FROM_NAME`	No	Default sender name	`Your App Name`

TLS vs. STARTTLS

Understanding SMTP security:

Port 587 (STARTTLS)
Port 465 (TLS/SSL)
Port 25 (Unencrypted)

Most common and recommended

SMTP_PORT=587
SMTP_SECURE=false

Connection starts unencrypted
Upgrades to TLS via STARTTLS command
Widely supported
Recommended by most providers

Implicit TLS

SMTP_PORT=465
SMTP_SECURE=true

Connection is encrypted from the start
Uses implicit TLS (SMTPS)
Older standard but still supported
Some providers require this

Development vs. Production

Development Setup

For development, consider using:

Log Provider (easiest):
EMAIL_PROVIDER=log

Ethereal Email (test SMTP service):

// Create test account at https://ethereal.email
SMTP_HOST=smtp.ethereal.email
SMTP_PORT=587
SMTP_USER=your-ethereal-email
SMTP_PASS=your-ethereal-password
SMTP_SECURE=false

Emails are caught, not sent - view them at ethereal.email

Gmail (for quick testing):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-gmail@gmail.com
SMTP_PASS=your-app-password
SMTP_SECURE=false

Production Setup

For production, use a reliable SMTP provider:

# .env.production
SMTP_HOST=smtp.production-provider.com
SMTP_PORT=587
SMTP_USER=production-user
SMTP_PASS=production-password
SMTP_SECURE=false
DEFAULT_FROM_EMAIL=noreply@yourdomain.com
DEFAULT_FROM_NAME=Your App Name

Troubleshooting

Error: 'Nodemailer not configured'

Missing or incomplete SMTP configuration.Solution:

Verify all required env vars are set: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS
Check for typos in variable names
Restart your application

Error: 'Connection timeout' or 'ECONNREFUSED'

Cannot connect to SMTP server.Solution:

Verify SMTP_HOST is correct
Check SMTP_PORT (587 or 465)
Ensure firewall allows SMTP connections
Try alternative port if blocked
Check if your ISP blocks SMTP

Error: 'Self-signed certificate'

SSL/TLS certificate issue.Solution: For development only, you can bypass (not recommended for production):

// In nodemailer.ts, add to transporter config:
tls: {
  rejectUnauthorized: false
}

For production, fix the certificate issue on your SMTP server.

Emails going to spam

Common deliverability issues:

Set up SPF record: Add SMTP server to domain’s SPF
Configure DKIM: Set up DKIM signing
Add DMARC policy: Configure DMARC for your domain
Use authenticated domain: Send from verified domain
Warm up IP: Gradually increase sending volume
Avoid spam triggers: Check email content for spam words

Slow email sending

SMTP is inherently slower than API-based providers.Improvements:

Use connection pooling (Nodemailer does this automatically)
Switch to API-based provider (Resend, Postmark) for batches
Use background jobs for large sends
Reduce batch size

Code Reference

The Nodemailer provider implementation:

src/lib/messaging/email/providers/nodemailer.ts

Key functions:

createNodemailerProvider() - Initialize provider (line 130)
getTransporter() - Create SMTP transport (line 37)
send() - Send single email (line 67)
sendBatch() - Send batch emails (line 96)

When to Use Nodemailer

Nodemailer is ideal when you:

Have existing SMTP infrastructure - Company email server, self-hosted solution

Need maximum flexibility - Full control over transport and configuration

Use unsupported provider - Provider doesn’t have a native ShipFree integration

Require offline capability - Local SMTP server for air-gapped systems

Consider alternatives if you:

Need high-volume batch sending (use Resend/Postmark)
Want simpler setup (use Resend/Postmark/Plunk)
Need maximum deliverability (use Postmark)
Want detailed analytics (use Resend/Postmark)

Additional Resources

Nodemailer Documentation

Official Nodemailer docs and guides

SMTP Guide

SMTP configuration reference

Ethereal Email

Test SMTP service for development

Email Testing

Testing strategies with Nodemailer

Next Steps

Set up SPF/DKIM

Configure DNS records for better email deliverability

Test with Ethereal

Use Ethereal Email to test without sending real emails

Monitor sending

Implement logging to track email delivery and failures

Getting Started

Core Features

Payment Providers

Email Providers

Configuration

Deployment

Nodemailer (SMTP)

Overview

Prerequisites

Setup Instructions

Step 1: Gather SMTP Credentials

Step 2: Configure Environment Variables

Step 3: Install Nodemailer

Step 4: Test Your Configuration

Common SMTP Providers

Features

Email Attachments

Custom Headers

Reply-To Address

Plain Text Alternative

Batch Email Sending

Environment Variables Reference

TLS vs. STARTTLS

Development vs. Production

Development Setup

Production Setup

Troubleshooting

Code Reference

When to Use Nodemailer

Additional Resources

Nodemailer Documentation

SMTP Guide

Ethereal Email

Email Testing

Next Steps

​Overview

​Prerequisites

​Setup Instructions

​Step 1: Gather SMTP Credentials

​Step 2: Configure Environment Variables

​Step 3: Install Nodemailer

​Step 4: Test Your Configuration

​Common SMTP Providers

​Features

​Email Attachments

​Custom Headers

​Reply-To Address

​Plain Text Alternative

​Batch Email Sending

​Environment Variables Reference

​TLS vs. STARTTLS

​Development vs. Production

​Development Setup

​Production Setup

​Troubleshooting

​Code Reference

​When to Use Nodemailer

​Additional Resources

Nodemailer Documentation

SMTP Guide

Ethereal Email

Email Testing

​Next Steps

Overview

Prerequisites

Setup Instructions

Step 1: Gather SMTP Credentials

Step 2: Configure Environment Variables

Step 3: Install Nodemailer

Step 4: Test Your Configuration

Common SMTP Providers

Features

Email Attachments

Custom Headers

Reply-To Address

Plain Text Alternative

Batch Email Sending

Environment Variables Reference

TLS vs. STARTTLS

Development vs. Production

Development Setup

Production Setup

Troubleshooting

Code Reference

When to Use Nodemailer

Additional Resources

Next Steps