N

Queue Support

Send emails in the background using Redis-backed job queues.

BullMQ (recommended)
npm install bullmq ioredis
Bull (legacy)
npm install bull

Queue Configuration

Mail.configure({
  // ... mailer config
  queue: {
    driver: 'bullmq',       // 'bullmq', 'bull', or 'sync'
    connection: {
      host: 'localhost',
      port: 6379,
    },
    defaultQueue: 'mail',
    prefix: 'nodemail',
    retries: 3,
    backoff: { type: 'exponential', delay: 1000 },
  },
});

Queue Drivers

DriverPackageDescription
bullmqbullmq + ioredisRecommended. Modern, actively maintained.
bullbullLegacy. Stable but no longer actively developed.
sync(none)Development/testing. Jobs are stored but not processed in background.

Sending Patterns

Queue immediately

await Mail.to('user@example.com')
  .subject('Welcome!')
  .html('<h1>Welcome!</h1>')
  .queue();

Queue with delay (seconds)

// Send in 60 seconds
await Mail.to('user@example.com')
  .subject('Follow Up')
  .html('<p>How are things going?</p>')
  .later(60);

Schedule for a specific time

// Send on Christmas
await Mail.to('user@example.com')
  .subject('Merry Christmas!')
  .html('<h1>Happy Holidays!</h1>')
  .at(new Date('2026-12-25T00:00:00'));

Queue a Mailable

// Via fluent API
await Mail.to('user@example.com').queue(new WelcomeEmail(user));
await Mail.to('user@example.com').later(60, new FollowUpEmail(user));
await Mail.to('user@example.com').at(scheduledDate, new ReminderEmail(user));

// Via Mail facade
await Mail.queue(new WelcomeEmail(user));
await Mail.later(new FollowUpEmail(user), 60);
await Mail.at(new WelcomeEmail(user), scheduledDate);

Processing Queued Emails

Start a worker to process queued emails:

// In your worker process
await Mail.processQueue();

// Or with a specific queue name
await Mail.processQueue('priority-mail');

QueueManager Direct API

For advanced usage, access the QueueManager directly:

import { QueueManager } from '@impruthvi/nodemail';

const queueManager = new QueueManager({
  driver: 'bullmq',
  connection: { host: 'localhost', port: 6379 },
  retries: 3,
  backoff: { type: 'exponential', delay: 1000 },
});

// Queue an email
await queueManager.queue(mailOptions);

// Queue with delay
await queueManager.later(mailOptions, 60);

// Schedule for a specific time
await queueManager.at(mailOptions, new Date('2026-12-25'));

// Process jobs
await queueManager.process(async (job) => {
  // Send the email
  return await provider.send(job.mailOptions);
});

// Get configuration
const config = queueManager.getConfig();

// Close connections
await queueManager.close();

QueueManager Methods

MethodSignatureDescription
queue()queue(mailOptions: MailOptions, queueName?: string): Promise<QueueJobResult>Add a job to the queue
later()later(mailOptions: MailOptions, delaySeconds: number, queueName?: string): Promise<QueueJobResult>Add a delayed job
at()at(mailOptions: MailOptions, date: Date, queueName?: string): Promise<QueueJobResult>Schedule a job for a specific time
process()process(handler: (job: QueuedMailJob) => Promise<MailResponse>, queueName?: string): Promise<void>Start processing jobs
close()close(): Promise<void>Close all queue connections
getConfig()getConfig(): QueueConfigGet the current queue configuration