SMTP Provider

The NexoMailer SMTP provider is a high-performance engine built directly on Node.js native sockets. It is designed for low-latency sending and maximum compatibility with all mail servers.

Installation

Install the SMTP module via npm:

npm install @nexomailer/smtp

(Alternatively, you can use pnpm add @nexomailer/smtp or yarn add @nexomailer/smtp).

Core Features

• Auto-STARTTLS: Automatically upgrades to secure connections if supported by the server.
• Connection Pooling: Reuses existing connections to reduce handshake overhead.
• Multi-Auth Support: Supports LOGIN, PLAIN, and XOAUTH2 (OAuth2) authentication.
• Smart Timeouts: Fine-grained control over connection and socket idle times.

Basic Configuration

Here is how you configure a standard SMTP fallback (like Gmail, SendGrid, or Mailgun) inside your NexoMailer instance.

import { NexoMailer } from '@nexomailer/core';
 
const mailer = new NexoMailer({
  providers: [
    {
      type: 'smtp',
      priority: 2, // Used as a fallback
      config: {
        host: 'smtp.gmail.com', // Your SMTP host
        port: 587,              // Port 587 for STARTTLS, 465 for implicit TLS
        auth: {
          user: process.env.SMTP_USER, // Your SMTP username/email
          pass: process.env.SMTP_PASS  // Your SMTP password or App Password
        }
      }
    }
  ]
});

Advanced Enterprise Setup

For high-volume production environments, you can fine-tune the low-level socket behavior to maximize throughput and prevent dropped connections.

config: {
  host: 'smtp.enterprise.com',
  port: 587,
  
  // PERFORMANCE POOLING
  // Keeps a pool of connections open so you don't do a TCP handshake for every email
  pool: true,
  // Maximum number of simultaneous connections to the SMTP server
  maxConnections: 10,
  
  // TIMEOUTS
  // How long to wait for the initial connection to be established
  connectionTimeout: 5000, // 5 seconds
  // How long to wait for a response during the SMTP conversation (e.g., waiting for '250 OK')
  socketTimeout: 10000,    // 10 seconds
  
  // SECURITY & TLS
  secure: false, // Set to true ONLY if you are using Port 465 (Implicit TLS)
  tls: {
    rejectUnauthorized: true, // Fail if the server's SSL certificate is invalid
    servername: 'smtp.yourdomain.com' // Specify SNI if the server hosts multiple domains
  },
  
  // CUSTOM GREETING
  // The hostname sent during the EHLO command. Helps with deliverability/reputation.
  name: 'my-custom-app' 
}

Authentication Methods

1. Standard (Username/Password)

Most common for services like Mailtrap, SendGrid, or Gmail App Passwords.

auth: {
  user: 'admin@yourcompany.com',
  pass: 'your_super_secret_password'
}

2. OAuth2 (XOAUTH2)

Highly recommended for modern Gmail/Google Workspace integration to avoid "Less Secure App" issues.

auth: {
  type: 'oauth2',
  user: 'admin@yourcompany.com',
  // Your temporary access token generated from Google Cloud Console
  accessToken: 'ya29.A0AR...'
}

Troubleshooting

Connection Timeouts

If you are behind a firewall or using a slow SMTP relay, increase the connectionTimeout and socketTimeout values.

SSL/TLS Errors

If you are using a self-signed certificate on a private internal SMTP server, you can temporarily disable strict TLS validation. (Only recommended for internal development, never for production facing the public internet):

tls: {
  rejectUnauthorized: false
}

[!TIP] Performance: Always enable pool: true if you are sending more than 10 emails per minute. This avoids the overhead of creating a new TCP/TLS connection for every single message.