API with NestJS #25. Sending scheduled emails with cron and Nodemailer

January 18, 2021

This entry is part 25 of 51 in the API with NestJS

So far, in this series, we’ve been creating an API that allows users to interact with our application. As soon as the client makes the request, we react to it and respond.

Sometimes though, we need to delay the execution of some logic or do so on a schedule. A common solution in the Unix world is cron. No wonder its syntax got adapted by various Node.js libraries.

In this article, we go through the cron syntax. We look into the @nestjs/schedule library that uses node-cron under the hood. We also use it together with the Nodemailer to schedule emails.

Setting up the Nodemailer

There are a few ways to set up the Nodemailer with NestJS. Although some libraries can integrate Nodemailer with NestJS, they don’t have a ton of downloads. Instead, we can use Nodemailer directly. First, let’s install it.

1	npm install nodemailer @types/nodemailer

To successfully send emails, we need a few environment variables:

.env

EMAIL_SERVICE=gmail

EMAIL_USER=nestjs.application@gmail.com

EMAIL_PASSWORD=...

# ...

app.module.ts

import { Module } from '@nestjs/common';

import { ConfigModule } from '@nestjs/config';

import * as Joi from '@hapi/joi';

@Module({

imports: [

ConfigModule.forRoot({

validationSchema: Joi.object({

EMAIL_SERVICE: Joi.string().required(),

EMAIL_USER: Joi.string().required(),

EMAIL_PASSWORD: Joi.string().required(),

// ...

})

}),

// ...

controllers: [],

providers: [],

})

export class AppModule {}

In this simple example, we are using Gmail. If you want to use Gmail with Nodemailer, you need to turn on the less secure apps access as stated in the official Nodemailer documentation.

The last thing to do is to create a service that initializes the Nodemailer.

email.service.ts

import { Injectable } from '@nestjs/common';

import { createTransport } from 'nodemailer';

import * as Mail from 'nodemailer/lib/mailer';

import { ConfigService } from '@nestjs/config';

@Injectable()

export default class EmailService {

private nodemailerTransport: Mail;

constructor(

private readonly configService: ConfigService

) {

this.nodemailerTransport = createTransport({

service: configService.get('EMAIL_SERVICE'),

auth: {

user: configService.get('EMAIL_USER'),

pass: configService.get('EMAIL_PASSWORD'),

}

});

}

sendMail(options: Mail.Options) {

return this.nodemailerTransport.sendMail(options);

}

email.module.ts

import { Module } from '@nestjs/common';

import EmailService from './email.service';

import { ConfigModule } from '@nestjs/config';

@Module({

imports: [ConfigModule],

controllers: [],

providers: [EmailService],

exports: [EmailService]

})

export class EmailModule {}

With the above approach, we could switch the Nodemailer to any other solution we want without much impact on the rest of the application.

Using the schedule module built into NestJS

The most straightforward way to start using cron with NestJS is to install the @nestjs/schedule package.

1	npm install @nestjs/schedule @types/cron

There is a very good explanation of this library in the official documentation and I recommend looking into it

We also need to import it in our AppModule.

app.module.ts

import { Module } from '@nestjs/common';

import { ScheduleModule } from '@nestjs/schedule';

@Module({

imports: [

ScheduleModule.forRoot(),

// ...

controllers: [],

providers: [],

})

export class AppModule {}

The ScheduleModule.forRoot method initializes the scheduler. It also registers all the cron jobs we define declaratively across our application.

Defining cron jobs in a declarative way

When we look up the declarative programming on Wikipedia, we see that it expresses the logic of a computation without describing its control flow. In NestJS, we can use various decorators that allow us to set up cron jobs. Thanks to their declarative approach, we don’t need to worry about what happens under the hood.

Cron utilizes its own string format for scheduling, which can vary across implementations. The node-cron library allows us to specify six sections. Each one represents a unit of time.

┌────────────── second (optional)

│ ┌──────────── minute

│ │ ┌────────── hour

│ │ │ ┌──────── day of the month

│ │ │ │ ┌────── month

│ │ │ │ │ ┌──── day of week (0 or 7 are Sunday)

│ │ │ │ │ │

* * * * * *

Not all systems allow us to specify the seconds. Even implementations in Node.js can vary because the cron package uses 0-6 for days of the week.

The asterisk (*) indicates that the event is scheduled to happen for any time unit value. Consider the following example:

emailScheduling.service.ts

import { Injectable } from '@nestjs/common';

import { Cron } from '@nestjs/schedule';

@Injectable()

export default class EmailSchedulingService {

@Cron('* * * * * *')

log() {

console.log('Hello world!');

}

The Cron decorator also accepts a JavaScript Date object.

Above, the log method is called for any second, minute, hour, day of the month, month, and day of the week. This means that cron calls the log method every second.

We can change this behavior by replacing an asterisk with a number. If we do that, cron executes the method only if the current time matches our cron expression. For example, writing @Cron('0 0 8 * * 1') means scheduling the method to run only on Monday at 8:00:00 AM.

There are a lot of possibilities and characters that we can use in our expressions. Some of the examples are:

0 30 11 * * 6,7 – 11:30:00 on Saturday, and Sunday,
0 0 8 * 12 5-7 – 8:00:00 on Friday, Saturday, and Sunday (only in December),
0 */15 10-12 * * * – every 15 minutes between 10AM and 12AM.

NestJS has more decorators that we can use to set up cron jobs. One of them is the @Interval() that we can use to run a method at an interval specified as a number of milliseconds.

@Interval(60000)

log() {

console.log('Called every minute');

}

Aside from the above, we also have the @Timeout() decorator that allows us to run a method once while specifying the timeout with milliseconds.

@Timeout(60000)

log() {

console.log('Called once after a minute');

}

Using the dynamic schedule API to send emails

Aside from using various decorators to schedule cron jobs, we can also use the schedule module manually. Let’s create a simple endpoint that allows our users to schedule emails. First, let’s define the structure of the request body.

emailSchedule.dto.ts

import { IsString, IsNotEmpty, IsDateString, IsEmail } from 'class-validator';

export class EmailScheduleDto {

@IsEmail()

recipient: string;

@IsString()

@IsNotEmpty()

subject: string;

@IsString()

@IsNotEmpty()

content: string;

@IsDateString()

date: string;

}

export default EmailScheduleDto;

Once we define the Data Transfer Object, we can deal with the controller.

emailSchedule.controller.ts

import {

Body,

Controller,

UseGuards,

Post,

} from '@nestjs/common';

import JwtAuthenticationGuard from '../authentication/jwt-authentication.guard';

import EmailSchedulingService from './emailScheduling.service';

import EmailScheduleDto from './dto/emailSchedule.dto';

@Controller('email-scheduling')

export default class EmailSchedulingController {

constructor(

private readonly emailSchedulingService: EmailSchedulingService

) {}

@Post('schedule')

@UseGuards(JwtAuthenticationGuard)

async scheduleEmail(@Body() emailSchedule: EmailScheduleDto) {

this.emailSchedulingService.scheduleEmail(emailSchedule);

}

Above, we allow only logged in users to request this endpoint. If you want to know more, check out API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies

The core logic of this scheduling resides in the EmailSchedulingService:

emailSchedule.service.ts

import { Injectable } from '@nestjs/common';

import EmailService from '../email/email.service';

import EmailScheduleDto from './dto/emailSchedule.dto';

import { SchedulerRegistry } from '@nestjs/schedule';

import { CronJob } from 'cron';

@Injectable()

export default class EmailSchedulingService {

constructor(

private readonly emailService: EmailService,

private readonly schedulerRegistry: SchedulerRegistry

) {}

scheduleEmail(emailSchedule: EmailScheduleDto) {

const date = new Date(emailSchedule.date);

const job = new CronJob(date, () => {

this.emailService.sendMail({

to: emailSchedule.recipient,

subject: emailSchedule.subject,

text: emailSchedule.content

})

});

this.schedulerRegistry.addCronJob(`${Date.now()}-${emailSchedule.subject}`, job);

job.start();

}

Above, we use the CronJob constructor to define a crone job. As a first argument, it takes either a cron pattern or a date. The second argument is a function that is executed at a given time.

With the addCronJob method, we add the job to the scheduler built into NestJS. We need to give it a unique name as a first argument. Thanks to doing so, we could access the job and stop it, for example.

cancelAllScheduledEmails() {

this.schedulerRegistry.getCronJobs().forEach((job) => {

job.stop();

})

}

Aside from starting cron jobs, we could also use the schduler to define intervals, and create timeouts

Summary

In this article, we’ve gone through both the Nodemailer and the cron. We’ve learned what a cron pattern is and how to create one. We’ve also integrated both the Nodemailer and the cron to work together to create an email scheduler. With that knowledge, we can create a lot more functionalities related to scheduling.

Series Navigation<< API with NestJS #24. Cache with Redis. Running the app in a Node.js clusterAPI with NestJS #26. Real-time chat with WebSockets >>