@bgroup/mailer NPM

`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: 'recipient@example.com',
        subject: 'Email Subject',
        module: 'module',
        data: {
            name: 'Alice',
            message: 'Hello, here is some additional information!',
        },
        from: 'sender@example.com',
        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: 'recipient@example.com',
    subject: 'Email with Attachments',
    module: 'module',
    data: {
        name: 'John Doe',
        message: 'Hello! Please find the attached files.',
    },
    from: 'sender@example.com',
    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',
    'your_email@example.com',
    'your_password'
);

const emailData = {
    to: 'recipient@example.com',
    subject: 'Email with Template',
    module: 'module_name',
    data: {
        name: 'John Doe',
        message: 'Hello! Please find the attached files.',
    },
    from: 'sender@example.com',
    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: 'your_email@example.com',
    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.