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

January 18, 2021

This entry is part 25 of 180 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 >>

8 Comments

Oldest

Newest Most Voted

Inline Feedbacks

View all comments

Anton

3 years ago

Hi, thanks for grate articles! I have a question, how to execute cron only in one child process?

PSPR

2 years ago

Reply to Anton

I’m also searching for the same asnwer, but im thinking to use pm2 to instantiate a separate node process for cron with loading minimal dependencies…

hans

2 years ago

Hello

What happens if the server restarts?
Is the cron job lost?
how to recover it?

Jeeban

1 year ago

Reply to hans

You can use the Task Scheduling Like This : @Cron(CronExpression.EVERY_10_SECONDS)

Last edited 1 year ago by Jeeban

Prem

1 year ago

Reply to hans

I keep a table with all the cron job details and update it when a job runs. If the server restarts, I check the table for pending jobs and add them to the job registry.

Anton

1 year ago

It seems you only need a mail address to begin sending mail : is that really so … why other ressource talks about using Web API or SMTP Relay

Anton

1 year ago

Reply to Anton

Response to my own question : yes you only need a mail but you need to make a two factor identification with gmail in order to get a nodemailer ID

Last edited 1 year ago by Anton

Christian

1 year ago

Thank you! Great article series overall! Love it! ❤️