Email Delivery Microservice for Node.js / ES2017 V2

This is a email delivery microservice from Pip.Services library. This microservice sends emails to specified recipients.

The microservice currently supports the following deployment options:

• Deployment platforms: Standalone Process
• External APIs: HTTP/REST

Quick Links:

• Download
• Develop
• Configure
• Run
• Use
• Source Documentation

Contract

Logical contract of the microservice is presented below. For physical implementation (HTTP/REST, Lambda, etc.), please, refer to documentation of the specific protocol.

class EmailMessageV1 {
  public from: string;
  public cc: string;
  public bcc: string;
  public to: string;
  public reply_to: string;
  public subject: string;
  public text: string;
  public html: string;
}

class EmailRecipientV1 {
  public id: string;
  public name: string;
  public email: string;
  public language: string;
}

interface IEmailV1 {
  sendMessage(
    context: IContext,
    message: EmailMessageV1,
    parameters: ConfigParams
  ): Promise<void>;
  sendMessageToRecipient(
    context: IContext,
    recipient: EmailRecipientV1,
    message: EmailMessageV1,
    parameters: ConfigParams
  ): Promise<void>;
  sendMessageToRecipients(
    context: IContext,
    recipients: EmailRecipientV1[],
    message: EmailMessageV1,
    parameters: ConfigParams
  ): Promise<void>;
}

Message subject, text and html content can be set by handlebars template, that it processed using parameters set. Here is an example of the template:

Dear {{ name }},
<p />
Please, help us to verify your email address. Your verification code is {{ code
}}.
<p />
Click on the
<a
  href="{{ clientUrl }}/#/verify_email?server_url={{ serverUrl }}&email={{ email }}&code={{ code }}"
  >link</a
>
to complete verification procedure
<p />
---<br />
{{ signature }}

Download

Right now the only way to get the microservice is to check it out directly from github repository:

git clone [email protected]:entinco/eic-services-infrastructure2.git

Pip.Service team is working to implement packaging and make stable releases available for your as zip downloadable archieves.

Develop

This document provides high-level instructions on how to build and test the microservice.

Environment Setup

This is a Node.js project and you have to install Node.js tools. You can download them from official Node.js website: https://nodejs.org/en/download/

After node is installed you can check it by running the following command:

node -version

Then you need to configure node tools:

# Install typescript compiler
npm install typescript -g

# Install mocha test runner
npm install mocha -g

To work with GitHub code repository you need to install Git from: https://git-scm.com/downloads

Installing

After your environment is ready you can check out microservice source code from the Github repository:

git clone [email protected]:entinco/eic-services-infrastructure2.git

Then go to the project folder and install dependent modules:

# Install dependencies
npm install

If you worked with the microservice before you can check out latest changes and update the dependencies:

# Update source code updates from github
git pull

# Update dependencies
npm update

Building

This microservice is written in TypeScript language which is transcompiled into JavaScript. So, if you make changes to the source code you need to compile it before running or committing to github. The process will output compiled javascript files into /bin folder.

tsc

When you do continuous edit-build-test cycle, you can run typescript compiler with --watch option to detect and compile changes you make automatically:

tsc --watch

Testing

Before you execute tests you need to set configuration options in config.yml file.

Command to run unit tests:

npm test

You can also execute benchmarks as:

npm run benchmark

Configure

Email delivery microservice configuration structure follows the standard configuration structure.

Service

Service has the following configuration properties:

• message: hashmap - Message default properties
  • from: string - sender address
  • cc: string - CC address
  • to: string - default recipient address
  • reply_to: string - Reply-To address
• connection: ConnectionParams - SMTP connection parameters
• credential: CredentialParams - SMTP credentials

Example:

- descriptor: "email:service:default:default:1.0"
  message:
    from: "[email protected]"
    to: "[email protected]"
  connection:
    service: "Gmail"
    host: "smtp.gmail.com"
    secure_connection: true
    port: 465
  credential:
    username: "[email protected]"
    password: "pass123"

Controllers

The controller components (also called endpoints) expose external microservice API for the consumers. Each microservice can expose multiple APIs (HTTP/REST, Lambda) and multiple versions of the same API type. At least one service is required for the microservice to run successfully.

Http

HTTP/REST controller has the following configuration properties:

• connection: object - HTTP transport configuration options
  • protocol: string - HTTP protocol - 'http' or 'https' (default is 'http')
  • host: string - IP address/hostname binding (default is '0.0.0.0')
  • port: number - HTTP port number

Example:

- descriptor: "email:controller:commandable-http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 3000

Run

Add config.yml file to the config folder and set configuration parameters. Example of microservice configuration:

---
- descriptor: "pip-services-commons:logger:console:default:1.0"
  level: "trace"

- descriptor: "email:service:default:default:1.0"
  message:
    from: "[email protected]"
    to: "[email protected]"
  connection:
    service: "Gmail"
    host: "smtp.gmail.com"
    secure_connection: true
    port: 465
  credential:
    username: "[email protected]"
    password: "pass123"

- descriptor: "email:service:commandable-http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

Start the microservice using the command:

node ./bin/main.js

Use

The easiest way to work with the microservice is to use client library. The complete list of available client libraries for different languages is listed in the Quick Links

If you use Node.js then you should add dependency to the client library into package.json file of your project

{
    ...
    "dependencies": {
        ....
        "client-email2-node": "^1.0.*",
        ...
    }
}

Inside your code get the reference to the client library

var client = new require("client-email2-node");

Define client configuration parameters that match configuration of the microservice external API

// Client configuration
var config = {
  connection: {
    protocol: "http",
    host: "localhost",
    port: 8080,
  },
};

Instantiate the client and open connection to the microservice

// Create the client instance
var client = client.EmailHttpClientV1(config);

try {
    // Connect to the microservice
    await client.open(null);
    // Work with the microservice
    ...
} catch (err) {
    console.error('Connection to the microservice failed');
    console.error(err);
}

Now the client is ready to perform operations

// Send email message to address
await client.sendMessage(null, {
  to: "[email protected]",
  subject: "Test",
  text: "This is a test message. Please, ignore it",
});

// Send email message to users
await client.sendMessageToRecipients(
  null,
  [
    { id: "123", email: "[email protected]" },
    { id: "321", email: "[email protected]" },
  ],
  {
    subject: "Test",
    text: "This is a test message. Please, ignore it",
  }
);

Acknowledgements

This microservice was created and currently maintained by:

• Sergey Seroukhov
• Danylo Kuznetsov