@plugcore/ds-email

Documentation can be found at the wiki.

Datasource: Email

This utility will help connect to an Email server (ex: SMTP server, GMAIL, Outlook 365, etc) to send our emails. It uses the datsources system, where every instance of the client will target an specific email server.

Internally it uses nodemailer to connect to any email server, but it also adds some helper functions to connect to a Google API Gmail account, which can be very helpful if you are using a gmail account to send your emails, or a GSuite account, where you can configure SPF, DKIM or DMARC records to secure your emails and evade SPAM filters.

Configuration

Inside our configuration file, for example {PROJECT_ROOT}/configuration/configuration.json, we will have to add a new entry for each email server we want to connect, like in this example:

{
    "connections": {
        "myemail": { // Connection id
            "type": "email", // Datasource type
            "host": "smtp.email.com", // SMTP Host
            "port": 587, // SMTP port
            "secure": false, // true for 465, false for other ports
            "auth": {
                "user": "user", // User/email
                "pass": "password",
            },
            "defaultFrom": { // Email address that will be used to send the emails
                "name": "Company name",
                "address": "[email protected]"
            }
        },
        ...
    },
    ...
}

For more information about configuration you can go to: https://nodemailer.com/smtp/

Usage

Once the connection is defined in the configuration we are ready to create a service decorated with @Service({ connection: 'myemail' }) that will be able to send emails through the configured server.

Basic example:

import { MailOptions, EmailAddress } from '@plugcore/ds-email';
 
// Service that will use the connection we defined before
@Service({ connection: 'myemail' })
export class EmailService { 
 
    constructor(
        // Connection to "myemail"
        private emailDataSource: EmailDataSource
    ) {}
 
    // Basic example
 
    public async sendEmail() {
        await this.emailDataSource.sendEmail(<MailOptions>{
            from: '[email protected]', // This field optional and it's recommended to leave it empty so the system will use the 
                                      // "defaultFrom" property from the configuration file
            to: <EmailAddress>{ name:'Customer Al', address: '[email protected]' },
            cc: [
                '[email protected]',
                { name:'Admin', address: '[email protected]' }
            ],
            subject: 'New receipt',
            html: `
                <div>
                    <img src="cid:embeddedlogo" title="Company logo">
                </div>
                <h2>Hi this is a title</h2>
                <p>This is text</p>
            `,
            attachments: [
                {
                    filename: 'logo.png',
                    path: '/path/to/logo.png',
                    cid: 'embeddedlogo'
                },
                {
                    filename: 'receipt.pdf',
                    content: createReadStream('/path/to/local/file.pdf')
                }
            ]
        });
    }
  
}

You can learn more about MailOptions at https://nodemailer.com/message/ and form file attch options at https://nodemailer.com/message/attachments/

Google API

In order to send emails safely using Google Suite accounts, we have created a special configuration. You can learn how to create your Oauth 2.0 certificate here: https://developers.google.com/gmail/api/auth/web-server, after this you will have to configure the datasource like in this example:

{
    "connections": {
        "myemail": { // Connection id
            "type": "email", // Datasource type
            "defaultFrom": {
                "name": "Company name",
                "address": "[email protected]"
            },
            "gSuiteApi": {
                    "clientEmail": "[email protected]",
                    "privateKey": "-----BEGIN PRIVATE KEY-----\nabc123...ab123==\n-----END PRIVATE KEY-----\n", // Important to scape the new lines with "\n"
                    "userId": "[email protected]" // Same value as from address
            }
        },
        ...
    },
    ...
}

With this you will be able to send emails through the Gmail API instead of an SMTP server.