Example of JavaScript integration: MailTrain#

This example demonstrates how to integrate the JavaScript API library into an existing project. The open source project Mailtrain was chosen as an example, in which you can see below how it has been integrated with the JavaScript API library.

Overview#

Mailtrain is a self hosted newsletter web based application built on Node.js (v14+) and MySQL (v8+) or MariaDB (v10+).

Project features:
  • Subscriber lists management
  • List segmentation
  • Custom fields
  • Email templates (including MJML-based templates)
  • Custom reports
  • Automation (triggered and RSS campaigns)
  • Multiple users with granular user permissions and flexible sharing
  • Hierarchical namespaces for enterprise-level situations
  • Builtin Zone-MTA for close-to-zero setup of mail delivery
Library integration:
  • Encrypt emails of subscribers before saving in DB
  • Decryption of email when they are rendered in the frontend
  • Encrypt/decrypt email templates
  • Decryption of email when backend send campaign email to the targeted recipients

Installation#

Using npm:

Configure the transformation#

The example illustrated in this pages is based on the following transformation configuration which can be created by following this tutorial and using this JSON configuration file.

Details of the transformation configuration:

  • One rights context is defined: Can TRANSFORM.
  • Two processing contexts are defined: Protect and Deprotect.
  • The Subscriber.Email data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers
  • The CampaignSettings.ReplyEmail data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers
  • The CampaignSettings.FromEmail data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers
  • The Template.Text data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers
  • The Template.Name data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers
  • The Template.Description data instance can be protected/deprotected using the "AES deterministic decryption sequence"/"AES deterministic encryption sequence" transformer sequences which are based on "AES deterministic encryption" transformers

Configuration of the API library#

The API library is installed and configured in the shared directory because it is used on the client and on the server.

Configuration files#

In this section we see how to configure the RPS API Library in order to use the transformation configuration you just created. You have to replace following parameters with the you retrieved when you created the transformation configuration in RPS CoreConfiguration:

  • {API_KEY_OF_CONFIGURATION} = It is the API Key of the transformation configuration
  • {SECRET_KEY_OF_CONFIGURATION} = It is the Secret Key of the transformation configuration
  • {ENGINE_HOST_NAME} = It is the RPS transformation services hostname
  • {AUTH_HOST_NAME} = It is the RPS OAuth2 authentication services hostname
Configuration file in the shared directory:#
Configuration file in the server directory:#
Engine authorization endpoint for getting token:#
Configuration file in the client directory:#

Examples of usages#

Here you can see how data is encrypted in the client and how data is decrypted in the server by calling the RPS Engine transform endpoint via the RPS API library.

Client:#
Server:#

Examples of encryption#

The following screen-shots shows you how data is rendered by the frontend of MailTrain frontend in two scenarii:

  1. RPS is not used, there is no integration with RPS API library. This is how the data is stored in the database of MailTrain, so data is fully protected.
  2. RPS is used via the integration of RPS API library in MailTrain. Data is rendered in clear to the final user allowing to him to use it.