0.2.3 • Published 4 months ago
@pixelplex/mail-service v0.2.3
Mail Service
Library for fast implementation of the functionality of sending email messages.
The sends messages them via email.
How to use
- create template for html, plain text and subject
- add
@pixelplex/mail-service
to your application - Call
MailModule.forRoot
from@pixelplex/mail-service
with specified gateways and options - send a message by calling
this.mailSenderService.sendEmail('test@gmail.com', { htmlPath: htmlTemplatePath, plainPath: plainTextTemplatePath, subjectPath: subjectTemplatePath }, {year: 20});
wheremailSenderService
isMailSenderService
Currently supported gateways:
- slack
- console
- smtp
- sendgrid
Didn't understand anything? Okay, let's see more details
Prepare templates
The service uses Handlebars as template engine. So all your email templates should be prepared as handlebars templates.
For sending message your templates folder should include this files:
{name}.handlebars
- body of your email where{name}
is just your template name for email. For examplewelcome.handlebars
for the welcome use email{name}.subject.handlebars
- subject (title) of your email. You can use subject field to specify subject directly. It will override subjectPath{name}.plain.handlebars
- subject (title) of your email. You can use plain field to specify plain directly. It will override plainPath
# welcome.subject.handlebars Welcome, {{name}}! This is subject
# welcome.handlebars
<html>
<head></head>
<body>
<p>Welcome, {{name}}!</p>
<p>How are you?</p>
</body>
</html>
# welcome.plain.handlebars
<html>
<head></head>
<body>
<p>Welcome, {{name}}!</p>
<p>How are you?</p>
</body>
</html>
Configuration
Name | Description | Example |
---|---|---|
gateways | Array of gateways to send email | ['slack'] |
customGateways | Array of custom gateways classes | [CustomGateway] |
smtp.host | Mail gateway host address | smtp.gmail.com |
smtp.port | Mail gateway port number | 586 |
smtp.username | Mail gateway username | username |
smtp.password | Mail gateway password | qh05780c2qcm034579 |
*.sender | Mail sender address | postmail@pixelplex.io |
slack.url | Hook URL in case you want to duplicate messages to Slack | https://hooks.slack.com |
sendgrid.apiKey | Sendgrid api key | oiqur9823uiofhaoafoe |
Trigger new message sending
1. Install npm package
yarn add @pixelplex/mail-service
2. Import MailModule in your module you'll send mail from:
import { Module } from '@nestjs/common';
import { MailModule } from '@pixelplex/mail-service';
import { AppService } from './app.service';
@Module({
controllers: [],
imports: [
MailModule.forRoot({
gateways: ['slack', 'smtp', 'console'],
slack: { url: 'hooks.slack.com' },
smtp: {
username: 'postmail@pixelplex.io',
sender: 'postmail@pixelplex.io',
host: 'smtp.ethereal.com',
port: 678,
password: 'password',
},
}),
],
providers: [AppService],
})
export class AppModule {}
3. Call sendEmail to send your mail:
import { Injectable } from '@nestjs/common';
import { MailSenderService } from '@pixelplex/mail-service';
@Injectable()
export class AppService {
constructor(private mailSenderService: MailSenderService) {}
async onModuleInit() {
this.mailSenderService.sendEmail(
'test@gmail.com',
// additionaly you can use plain: plainText, subject: subjectText to specify plain or subject directly
// if so, plainPath or subjectPath will be ignored
{ htmlPath: htmlTemplatePath, plainPath: plainTextTemplatePath, subjectPath: subjectTemplatePath },
{ year: 20 },
);
}
}
{year: 20}
is the object with data which will used as payload data during processing your handlebars template.
Custom gateways
To add custom gateways, provide class, that extends IGateway to customGateways options
@Injectable()
class CustomGateway implements IGateway {
async send(to: string, content: Content): Promise<void> {
console.log('this is custom gateway');
}
}
MailModule.forRoot({ customGateways: [CustomGateway] });