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

• Install the optional peer dependencies @nestjs/bull bull for your current NestJS version
• 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