Global Configuration

This page provides a complete reference for the NexoMailer constructor options. Every field listed here is natively supported by the SDK.

Installation

To get started with the global setup, you will need the core SDK and any optional modules you plan to use.

Using npm (recommended):

npm install @nexomailer/core @nexomailer/providers @nexomailer/analytics

(Alternatively, you can use pnpm add or yarn add with the same package names).

1. Environment Variables (.env)

Before writing any code, it is highly recommended to store all your sensitive API keys and connection strings in a .env file at the root of your project.

# Example .env file

# Providers
RESEND_API_KEY="re_123456789"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"

# Analytics (MongoDB)
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/nexomailer"

# Queue (Redis)
REDIS_HOST="127.0.0.1"
REDIS_PORT="6379"

# AI Personalization
OPENAI_API_KEY="sk-proj-..."

2. Best Practice: Create a Reusable Instance

In a modern Node.js application, you should not initialize NexoMailer every time you want to send an email.

Instead, create a single reusable instance (a Singleton) in a dedicated file, configure it once, and then export it so the rest of your app can use it easily. NexoMailer fully supports both TypeScript/ES Modules and standard CommonJS (Node.js).

`src/lib/mailer.ts`

import { NexoMailer } from '@nexomailer/core';
 
// 1. Initialize once
export const mailer = new NexoMailer({
  providers: [
    { 
      type: 'resend', 
      priority: 1, 
      config: { apiKey: process.env.RESEND_API_KEY } 
    }
  ],
  analytics: { mongodbUri: process.env.MONGODB_URI }
});
 
// 2. You must call init() before the app starts handling requests
export async function initializeMailer() {
  await mailer.init();
  console.log('✅ NexoMailer Engine Ready');
}

Usage anywhere in your app:

import { mailer } from '@/lib/mailer';
 
await mailer.send({
  to: 'user@example.com',
  subject: 'Hello World',
  html: '<h1>Welcome</h1>'
});

Complete Configuration Example

Here is a full-featured setup including all optional modules, with line-by-line explanations.

import { NexoMailer } from '@nexomailer/core';
 
// Initialize the core mailer engine
const mailer = new NexoMailer({
  
  // 1. Providers (Required: At least one provider must be defined)
  // These are the services that actually send the email.
  providers: [
    { 
      type: 'resend', // We are using Resend as our primary provider
      priority: 1,    // Priority 1 means this is tried first
      config: { 
        // Pass your API key. NEVER hardcode this, always use environment variables.
        apiKey: process.env.RESEND_API_KEY 
      } 
    },
    { 
      type: 'smtp',   // We are using a standard SMTP server as a fallback
      priority: 2,    // Priority 2 means this is only used if Priority 1 fails
      config: { 
        host: 'smtp.gmail.com', // Your SMTP server address
        port: 587,              // Standard TLS port
        auth: { 
          user: process.env.SMTP_USER, // Your SMTP username
          pass: process.env.SMTP_PASS  // Your SMTP password
        } 
      } 
    }
  ],
 
  // 2. Analytics (Optional: 100% Private Persistence)
  // This module saves every email event directly to your own database.
  analytics: {
    // Your MongoDB connection string. 
    mongodbUri: process.env.MONGODB_URI,
    // (Optional) Tag all records with a project ID for multi-tenant apps
    projectId: 'my-saas-app',
    // (Optional) Mark these records as production or development
    environment: 'production',
    // (Optional) How many days to keep the logs before auto-deleting them
    retentionDays: 90
  },
 
  // 3. Tracking (Optional: Engagement Tracking)
  // This module tracks if users open your emails or click your links.
  tracking: {
    enabled: true, // Turn the entire tracking system on or off
    // The base URL where your tracking server is hosted (see Tracking Module docs)
    baseUrl: 'https://api.myapp.com/api',
    opens: true,   // Track when an email is opened (adds a 1x1 tracking pixel)
    clicks: true   // Track when links inside the email are clicked (rewrites URLs)
  },
 
  // 4. AI Personalization (Optional)
  // This module uses LLMs to optimize subject lines and personalize content.
  ai: {
    provider: 'openai', // You can use 'openai' or 'openrouter'
    apiKey: process.env.OPENAI_API_KEY, // Your LLM API key
    model: 'gpt-4o',    // The specific model to use
    temperature: 0.7    // Creativity level of the AI (0.0 to 1.0)
  },
 
  // 5. Queue & Scheduling (Optional)
  // This module uses BullMQ and Redis to process emails in the background.
  queue: {
    redis: { 
      host: 'localhost', // Your Redis server host
      port: 6379         // Your Redis server port
    },
    concurrency: 5       // How many emails to process simultaneously
  },
 
  // 6. Branding & Style (Optional)
  // Default values passed to the AI module to ensure tone consistency.
  branding: {
    companyName: 'NexoDev',
    tone: 'Professional and helpful',
    websiteUrl: 'https://nexodev.com'
  }
});

Field Reference

1. `providers` (Array)

A list of email service providers. NexoMailer will use these for sending and failover.

type: 'smtp' | 'resend' | 'ses'.
priority: Number (lower is tried first).
weight: (For weighted strategy) Percentage of traffic.
config: Provider-specific credentials.

2. `analytics` (Object)

Handles data persistence.

mongodbUri: Your MongoDB connection string.
projectId: Used to filter data in multi-tenant apps.
environment: Defaults to 'development'.

3. `tracking` (Object)

Configuration for link rewriting and pixels.

enabled: Global toggle.
baseUrl: The root URL where your Tracking Middleware is mounted.
opens/clicks: Toggle individual tracking types.

4. `ai` (Object)

LLM integration settings.

provider: 'openai' | 'openrouter'.
model: Model name (e.g., gpt-4o, anthropic/claude-3).
maxTokens: Token limit for responses.

5. `queue` (Object)

Redis-backed background processing.

redis: Object containing host, port, password.
concurrency: Number of simultaneous emails to process.

6. `failover` (Object)

strategy: 'sequential' (Priority-based) or 'weighted' (Load-balanced).
maxRetries: Number of attempts per provider.

Initialization

Always initialize the SDK before using it to ensure all plugins and database connections are ready.

// Connects to MongoDB, Redis, and initializes the provider pool
await mailer.init();
 
console.log('NexoMailer is ready to send!');

[!TIP] Environment Variables: Never hardcode your API keys. Always use process.env or a secret manager.

Architecture Overview Native SMTP Engine

Global Configuration

Installation

1. Environment Variables (.env)

2. Best Practice: Create a Reusable Instance

src/lib/mailer.ts

Usage anywhere in your app:

Complete Configuration Example

Field Reference

1. providers (Array)

2. analytics (Object)

3. tracking (Object)

4. ai (Object)

5. queue (Object)

6. failover (Object)