@nestjs-modules/mailer Documentation

You can define multiple SMTP servers or transport types (SMTP, SES, Sendmail, Stream, JSON, or custom) by using the transports key in forRoot(). Each transporter is assigned a unique name. To use a specific transporter when sending an email, pass the transporterName property in the sendMail options.

// Configuration
MailerModule.forRoot({
  transports: {
    primary: {
      host: 'smtp.example.com',
      port: 587,
      auth: { user: 'primary@example.com', pass: 'pass1' },
    },
    secondary: {
      host: 'smtp.other.com',
      port: 587,
      auth: { user: 'secondary@other.com', pass: 'pass2' },
    },
    ses: {
      SES: { /* AWS SES config */ },
    },
  },
  defaults: {
    from: '"No Reply" <noreply@example.com>',
  },
  template: {
    dir: __dirname + '/templates',
    adapter: new HandlebarsAdapter(),
  },
})

// Usage
await this.mailerService.sendMail({
  transporterName: 'secondary',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<b>Hello</b>',
});

Use MailerBatchService to send a collection of emails efficiently with built-in concurrency control. This service is ideal for tasks like newsletters where you need to manage how many emails are being sent simultaneously to avoid overwhelming your SMTP server or hitting rate limits.

To use it, inject MailerBatchService into your provider and call the sendBatch method with an array of messages and a concurrency limit.

import { MailerBatchService } from '@nestjs-modules/mailer';

@Injectable()
export class NewsletterService {
  constructor(private readonly batchService: MailerBatchService) {}

  async sendNewsletter(subscribers: string[]) {
    const result = await this.batchService.sendBatch({
      messages: subscribers.map((email) => ({
        to: email,
        subject: 'Weekly Newsletter',
        template: 'newsletter',
        context: { email },
      })),
      concurrency: 10,
    });

    console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);
    return result;
  }
}

To use multiple email providers, define a primary transporter in the MailerModule.forRoot() configuration and register additional transporters at runtime using the MailerService.addTransporter() method. This allows you to separate transactional and marketing emails or implement failover mechanisms.

1. Set the default transporter: Use MailerModule.forRoot() to define the base configuration and the primary transport object.
2. Register additional transporters: Inject MailerService into a provider and call addTransporter(name, transportOptions) to register named transporters.

// 1. Define the default transporter in your module
MailerModule.forRoot({
  defaults: {
    from: '"App" <noreply@example.com>',
  },
  transport: {
    host: 'smtp.primary.com',
    port: 587,
    auth: {
      user: 'primary@example.com',
      pass: 'password',
    },
  },
});

// 2. Register additional transporters at runtime
@Injectable()
export class EmailService {
  constructor(private readonly mailerService: MailerService) {
    this.mailerService.addTransporter('marketing', {
      host: 'smtp.marketing.com',
      port: 587,
      auth: {
        user: 'marketing@example.com',
        pass: 'password',
      },
    });

    this.mailerService.addTransporter('backup', {
      host: 'smtp.backup.com',
      port: 587,
      auth: {
        user: 'backup@example.com',
        pass: 'password',
      },
    });
  }
}

If you need to customize how transporters are created, implement the MailerTransportFactory interface. This allows you to inject custom logic into the transport creation process, such as using specific nodemailer configurations or dynamic settings.

To use your custom factory, register it using the MAILER_TRANSPORT_FACTORY provider within the extraProviders array of MailerModule.forRootAsync().

import { MailerTransportFactory, MAILER_TRANSPORT_FACTORY } from '@nestjs-modules/mailer';
import { createTransport } from 'nodemailer';

// 1. Implement the interface
export class CustomTransportFactory implements MailerTransportFactory {
  createTransport(options?: any) {
    return createTransport({
      // your custom transport configuration
    });
  }
}

// 2. Register via forRootAsync
MailerModule.forRootAsync({
  useFactory: () => ({
    transport: { host: 'smtp.example.com', port: 587 },
  }),
  extraProviders: [
    {
      provide: MAILER_TRANSPORT_FACTORY,
      useClass: CustomTransportFactory,
    },
  ],
})