@goodrequest/grmailer

GR Mailer

Mail client for GR projects. Transpiled as both ESM & CJS module.

Documentation for ejs templates used by this library can be found on Goodrequest web wiki

ESM vs. CJS module

Here is the link used to setup this hybrid package.

TODO: write differences between ESM & CJS modules

Installation

npm i --save @goodrequest/grmailer

Initialization

createInstance static method returns tuple with GRMailer instance and verifyConnection promise. This promise can be ignored, or program can exit (with error code) when promise fails. Decision behind this is, that one can create & export mailer instance without waiting for promise, but sometimes it is useful to know, that email client cannot be reached.

import config from 'config'
import { GRMailer } from '@goodrequest/grmailer'

const emailConfig = config.get('email')

const [instance, promise] = GRMailer.createInstance(emailConfig)
promise.catch((err) => {
    console.error('[GRMailer]', err)
	process.exit(1)
})

You can pass additional options:

import config from 'config'
import { GRMailer } from '@goodrequest/grmailer'

import { emailLogger } from '../utils/logger'

const emailConfig = config.get('email')

GRMailer.createInstance(emailConfig, {
	logger: emailLogger
})ik

Options

Initialization config interface:

export interface IEmailConfig {
	host: string
	port: number
	secure: boolean
	auth: {
		user: string
		pass: string
	}
	from: string
	tls: {
		rejectUnauthorized: boolean
	}
}

Initialization options interface:

export interface IEmailOptions {
	logger?: any
	emailLogFileName?: string
	disableConnectionMessage?: boolean
	disableConnectionVerification?: boolean
}

• emailLogFileName: filename for winston, string interpolation can be used
• disableConnectionMessage: when set to true, no connection message will be shown after connecting
• disableConnectionVerification: when set to true, verifyEmailConnection will not be called when creating new mailer instance

ENV

Config JSON:

email: {
		host: process.env.SMTP_HOST,
		port: Number(process.env.SMTP_PORT),
		secure: Number(process.env.SMTP_PORT) === 465,
		auth: {
			user: process.env.SMTP_USER,
			pass: process.env.SMTP_PASSWORD
		},
		from: process.env.SMTP_FROM_ADDRESS,
		tls: {
			rejectUnauthorized: false
		}
	},

ENV example

SMTP_HOST=0.0.0.0
SMTP_PORT=1025
SMTP_USER=admin
SMTP_PASSWORD=admin
SMTP_FROM_ADDRESS=[e-mail]

Usage

1. Remove old code & add library

link to commit in the Backend project template which removes old email templates and add this library. Code can be found in the libs/email branch

2. Create instance

Like shown in the Initialization chapter

It creates class instance based on provided config, which means you can use multiple mail providers, or one with different accounts from one application. createInstance return tuple of [GRMailer instance, Promise].

Promise should be used to verify connection to email provider. It is the same promise returned from verifyEmailConnection method.

3. Save & export instance

It is recommended export instance from one file (e.g. emailService). So it can be imported from anywhere in the project.

4. Use Mailer

There are methods that uses already existing templates, or you can

Output

After connecting to email client, library will output green message.

When connection fails, library will output red error message.

Output can be disabled by setting disableConnectionMessage to false

API

• static createInstance(config: IEmailConfig, options?: IEmailOptions): [GRMailer, Promise<void>]: Static method used to create mailer class instances
• verifyEmailConnection(): Promise<void>: Used to verify connection to email client
• sendMail(emailData: SendMailOptions): Promise<any>: General method for sending emails
• sendMailWithTemplate(templatePath: string, to: string, translations: IPasswordResetTexts): Promise<any>: General method for sending emails, when you need to use different ejs file.
• sendPasswordResetEmail(to: string, translations: IPasswordResetTexts): Promise<any>: Method for sending password reset emails. It uses passwordReset.ejs template to render email
• sendInvitationEmail(to: string, translations: IInvitationEmailTexts): Promise<any>: Method for sending invitation emails. It uses invitation.ejs template to render email
• sendVerificationEmail(to: string, translations: IEmailVerificationTexts): Promise<any>: Method for sending verification emails. It uses emailVerification.ejs template to render email
• sendUniversalEmail(to: string, translations: IUniversalEmailTexts): Promise<any>: Method for sending other types of emails. It uses universal.ejs template to render email

Notes

• Chalk needs to on version < 5.0.0, since it is only ESM module from version 5.0.0 onwards
• This library does not contain tests, since we usually don't tests email methods in projects, but just mock them for tests.