Web & Söhne is Austria's leading expert in programming and implementing complex and large web projects.

Introduction

• The aim of this module is to provide an easy-to-use interface for sending Emails in a non-blocking manner in NestJS. You can either send Emails directly using the promise-based NodemailerModule or queueing the mails externally using EmailQueueService, which uses a Bull queue in the background.

Requirements

• NestJS v8.0.0+
• [Optional] for Email queueing: One or many redis instance(s)

Usage - Simple Nodemailer Service

• Import NodemailerModule and initialize it with NodemailerModule.init(data)

import { NodemailerModule } from '@webundsoehne/email'

@Module({
    imports: [NodemailerModule.init(nodemailerOptions: EmailConfigOptions)]
})
export class ServerModule {}

You can then inject the NodemailerService in your Injectable Class of choice and use the async sendEmail method to send an Email.

import { NodemailerService } from '@webundsoehne/email'

@Injectable()
export class GreetingService {
    constructor(private mailService: NodemailerService) {}
    
    async sendGreet(): Promise<void> {
        await mailService.sendEmail({
          from: '[email protected]',
          to: '[email protected]',
          subject: 'Hello World!',
          text: 'Have a nice day!',
          html: '<b>Have a nice day!</b>'
        })
    }
}

• After you have initialized NodemailerModule it will provide a NodemailerService in global scope. Make sure to only initialize the NodemailerModule once!

Initialization object (EmailConfigOptions)

• This object must be provided during initialization

Type | Required | Description ------- | --------------- | ------------ EmailConfigOptions (partial) nodemailer SMTP transport options | true | used to construct a nodemailer SMTP transport - all possible options please see https://nodemailer.com/smtp/

e.g.

{
    host: 'smtp.host.com',
    port: 587,
    auth: { user: 'bob', pass: 'bob' }
}

Advanced usage - Email Queue

• To get started import EmailModule and initialize it with EmailModule.init(data)

import { EmailModule } from '@webundsoehne/email'

@Module({
    imports: [EmailModule.init(data: EmailInitData)]
})
export class ServerModule {}

• After you have initialized EmailModule it will provide a EmailQueueService in global scope. Make sure to only initialize the EmailModule once!

Initialization object (EmailInitData)

• This object must be provided during initialization

Key | Type | Required | Description --------------------- | ------- | --------------- | ------------ nodemailerOptions | EmailConfigOptions (partial) (nodemailer SMTP transport options) | true | used to construct a nodemailer SMTP transport - all possible options please see https://nodemailer.com/smtp/ bullQueueOptions | BullModuleOptions | true | used to register a new BullQueue (queue name: email) - this is where you provide the details for your redis instance(s): possible options please see https://docs.nestjs.com/techniques/queues#queues defaultBullOptions | JobOptions | false | these options will be passed to every job you append to the queue (you also have the possibility to specify the options for every job you append on your own) customQueueProcessor | EmailQueueProcessor | false | You can use this class to override behavior of the queue processor (or add your own event listeners see https://docs.nestjs.com/techniques/queues#event-listeners)

Send Emails

You do not have to import the module more than once! EmailQueueService will be registered in global scope!

import { EmailQueueService, Email } from '@webundsoehne/email'

@Injectable()
export class MyService {
    constructor (private mailService: EmailQueueService) {}

    public sendMail(data: Email, options?: JobOptions) {
        this.mailService.sendEmail(data, options)
    }
}

• after you call sendMail(data: Email) a new job will be automatically appended to the queue!
• options are bull JobOptions (if you provided them during initialization you can overwrite them per email you want to send here)

Email interface

Key | Type | Required | Description --------------------- | ------- | --------------- | ------------ from | string | false | Set sender's address to | string | true | Set recipient address subject | string | true | Set subject text | string | true | Set email text bcc | string | false | Set bcc (blindcopy) email address cc | string | false | Set cc email address html | string | false | Set HTML E-Mail content attachments | EmailAttachment[] | false | Set file attached to email

Stay in touch

• Do you have any questions?
• Author: Backend Team; Markus Schüttengruber
• Website: Web & Söhne