@bgroup/mailer
v1.0.3
Published
Node JS Basic application
Downloads
12
Keywords
Readme
BG-mailer
📧
BG-mailer is a powerful tool for sending dynamic HTML emails. With BG-mailer, you can generate a token associated with an application, store it in the database, and use that information to customize the HTML template before sending the email.
Key Features
The heart of BG-mailer is the MailManager
class, which manages the entire email sending process. There are two main
functions you need to know to use BG-mailer:
hasPermission
: This function checks whether the provided token belongs to an application registered in the database.send
: This function sends the email. It takes the parameters{to, subject, module, data, attachments}
. Where:to
: Recipient's email address.subject
: Email subject.module
: Module to fetch from the database.data
: Values to be set in the HTML document.attachments
: An array of objects with the structure{ filename: "file name", path: "file path" }
.
Installation
Installing BG-mailer is straightforward. You just need to run the command npm i
to install all the dependencies.
import { MailManager } from '@bgroup/mailer/manager';
Methods :
hasPermission(token: string)
: Verifies if a token has permissions to access the mail service.getData(data: any, module: any)
: Retrieves necessary data to construct email content. Processes email templates with provided data.send({ to, subject, module, data, from, attachments }: IDataSend)
: Sends an email using the provided data.Other private methods like
setInfo
,findChildrenTemplates
,insertValueIntoChildren
,getAdditionals
,#findTemplate
,processChildren
,getTpl
,setDataTpl
: These methods are helpers used to process data, templates, and attachments before sending the email.
Use case sending an email :
import { MailManager } from '@bgroup/mailer/manager';
const mailerManager = new MailManager();
const hasPermission = await mailerManager.hasPermission('token');
if (hasPermission) {
const emailData = {
to: '[email protected]',
subject: 'Email Subject',
module: 'module',
data: {
name: 'Alice',
message: 'Hello, here is some additional information!',
},
from: '[email protected]',
attachments: [
{
filename: 'file.pdf',
path: '/path/to/file.pdf',
},
],
};
const emailSent = await mailerManager.send(emailData);
if (!emailSent.error) {
console.log('Email sent successfully!');
} else {
console.error('Error sending email:', emailSent.error);
}
}
Use case sending mails with files :
import { MailManager } from '@bgroup/mailer/manager';
const mailerManager = new MailManager();
const emailData = {
to: '[email protected]',
subject: 'Email with Attachments',
module: 'module',
data: {
name: 'John Doe',
message: 'Hello! Please find the attached files.',
},
from: '[email protected]',
attachments: [
{
filename: 'document.pdf',
path: '/path/to/document.pdf',
},
{
filename: 'image.jpg',
path: '/path/to/image.jpg',
},
],
};
const emailSent = await mailerManager.send(emailData);
if (!emailSent.error) {
console.log('Email with attachments sent successfully!');
} else {
console.error('Error sending email with attachments:', emailSent.error);
}
passing the template parameter :
const mailerManager = new MailManager();
mailerManager.setCredentials(
'mail.example.com',
'587',
'[email protected]',
'your_password'
);
const emailData = {
to: '[email protected]',
subject: 'Email with Template',
module: 'module_name',
data: {
name: 'John Doe',
message: 'Hello! Please find the attached files.',
},
from: '[email protected]',
attachments: [
{
filename: 'document.pdf',
path: '/path/to/document.pdf',
},
],
template:
'<html><body><h1>Hello, {{name}}!</h1><p>{{message}}</p></body></html>',
variables: {
name: 'John Doe',
message: 'Hello! Please find the attached files.',
},
};
const emailSent = await mailerManager.send(emailData);
if (!emailSent.error) {
console.log('Email sent successfully!');
} else {
console.error('Error sending email:', emailSent.error);
}
you can also pass a template and variables only :
import { MailManager } from '@bgroup/mailer/MailManager';
const mailerManager = new MailManager();
mailerManager.setCredentials({
host: 'smtp.example.com',
port: '587',
user: '[email protected]',
pass: 'your_email_password',
});
const emailData = {
template: '<html><body><h1>{{name}}</h1><p>{{message}}</p></body></html>',
variables: {
name: 'Bob',
message: 'This is a test email with template and variables.',
},
};
const emailSent = await mailerManager.send(emailData);
if (!emailSent.error) {
console.log('Email sent successfully!');
} else {
console.error('Error sending email:', emailSent.error);
}
In this example, MailManager is instantiated, the connection credentials are established, and the e-mail data is defined. The template parameter is included with the content of the HTML template and variables with the values to be replaced.
Contributing 🎁
Please feel free to contribute to the development of Mailer
. You can clone the repository, create a new branch for
your features or fixes, and submit a pull request.