@webundsoehne/email NPM

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: 'hello@email.com',
          to: 'greetings@world.com',
          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/

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