Older version

You're reading the docs for v2 (2.3.x). The latest version is v4.

Read the v4 guide · Migrate from v2 to v3 · Migrate from v3 to v4 · Versions & upgrading

Sending Emails

Inject the Service

import { Injectable } from '@nestjs/common';
import { MailerService } from '@nestjs-modules/mailer';

@Injectable()
export class NotificationService {
  constructor(private readonly mailerService: MailerService) {}
}

sendMail() accepts the same fields as nodemailer email message.

Plain Text / HTML

Send a simple email without templates:

await this.mailerService.sendMail({
  to: 'user@example.com',
  from: 'noreply@example.com',
  subject: 'Hello World',
  text: 'Plain text content',
  html: '<b>HTML content</b>',
});

With Templates

Use your configured template engine. The file extension (.hbs, .pug, .ejs) is appended automatically:

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Welcome!',
  template: 'welcome',       // resolves to templates/welcome.hbs
  context: {                  // data passed to the template
    name: 'John Doe',
    code: 'cf1a3f828287',
  },
});

With Absolute Path

You can use an absolute path to the template file:

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Welcome!',
  template: `${__dirname}/welcome`,
  context: {
    name: 'John Doe',
  },
});

TIP

When using absolute paths, make sure template files are copied to the dist folder at build time. See Copy Templates to dist.

Attachments

Send emails with file attachments:

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      path: '/absolute/path/to/invoice.pdf',
    },
  ],
});

Multiple Attachments

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Report',
  template: 'report',
  context: { title: 'Monthly Report' },
  attachments: [
    // File from disk
    { filename: 'report.pdf', path: '/path/to/report.pdf' },
    // Buffer
    { filename: 'data.csv', content: Buffer.from('id,name\n1,John') },
    // String content
    { filename: 'notes.txt', content: 'Some notes here' },
    // URL (nodemailer will fetch it)
    { filename: 'logo.png', path: 'https://example.com/logo.png' },
  ],
});

Inline Images (Embedded)

Embed images directly in the HTML using cid:

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Newsletter',
  html: '<img src="cid:logo" alt="Logo" />',
  attachments: [
    {
      filename: 'logo.png',
      path: '/path/to/logo.png',
      cid: 'logo',
    },
  ],
});

See Nodemailer attachments docs for all options.

Custom Headers

await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hello!</p>',
  headers: {
    'X-Custom-Header': 'custom-value',
    'X-Priority': '1',
  },
});

Reply-To and Threading

await this.mailerService.sendMail({
  to: 'user@example.com',
  replyTo: 'support@example.com',
  subject: 'Re: Your ticket',
  html: '<p>We received your request.</p>',
  inReplyTo: '<original-message-id@example.com>',
  references: ['<original-message-id@example.com>'],
});

Using a Specific Transporter

When you have multiple transporters configured, specify which one to use:

await this.mailerService.sendMail({
  transporterName: 'secondary',
  to: 'user@example.com',
  subject: 'Sent via secondary SMTP',
  html: '<p>Hello!</p>',
});

See Multiple Transporters for setup instructions.