AppSuite:OX Monetization Engage

OX Engage

OX Engage is an Open-Xchange patented technology that enables the injection of messages into the email stream of any user using the Internet Message Access Protocol (IMAP) [Patent "Ad hoc injection of IMAP objects" (US 9531785 B1) see United States Patent or Google Patents].

These IMAP objects may appear in the inbox of a user on any IMAP capable device, and may feel like an email to the user, although the IMAP objects were never sent over a SMTP server or protocol. Information that is stored in these IMAP objects can include advertising, promotions, service alerts or any other content. When a mail client requests a list of emails for an IMAP user folder from the IMAP server, the IMAP server will ad-hoc inject IMAP objects into the customer’s inbox.

The rules that define which objects will be injected, in which schedule and to which target audience, as well as the position of the message in the user’s inbox may depend on object- and/or user profiles and other targeting parameters.

Please Note: OX Engage is only available for OX App Suite as part of the OX Monetization Program. Please contact Open-Xchange Sales for further information.

Product Description

OX Engage enables the injection of messages into any email client, such as OX App Suite, Open-Xchange mobile mail clients or other clients using the IMAP protocol.

Campaigns are managed in the Campaign Management Platform (CMP). Once the campaign has been scheduled, the CMP interacts with the Mail Injection Middleware (MIM), which downloads and stores the campaigns and all related user data in order to transfer the contexts to the OX Dovecot Pro server when the user is active.

In other words, when a new campaign is scheduled in the CMP, the corresponding mail template and per-user data are exported and stored in an Amazon S3 compatible bucket. The successful export is followed by a push event to MIM, which then pulls the data and stores it locally in Cassandra for fast lookups and retrieval.

Cassandra is a distributed database for managing large amounts of structured data across many commodity servers, while providing highly available service and no single point of failure.

On user login, any active campaigns for that user are requested based on the data stored in Cassandra. This lookup happens asynchronously so as not to block the login procedure. If not cached locally yet, OX Dovecot Pro also requests the mail templates from MIM.

A more detailed technical overview of OX Engage can be found at http://software.open-xchange.com/products/ads/doc/OX_Engage_Product_Guide_1_0_0.pdf

Availability

OX Engage is available either on-premise in your data centre or hosted by Open-Xchange with OX as a Service (OXaaS).

OX Monetization Program

Open-Xchange provides OX Engage as a product for customers who wish to reach more of their customers via email and increase revenue potential at the same time.

OX Engage provides telcos and service providers the ability to display emails in their customers’ inboxes with our patented solution and monetize users irrespective of their preferred email client.

Requirements

  • A Linux operating system (without graphical user interface). Supported are: Debian 9 (Stretch), Red Hat Enterprise Linux 7, CentOS 7. Systemd is required as init system.
  • OpenJDK JRE 8
  • Cassandra >= 3.9 (Data storage; Tested with 3.11.1)
  • AWS S3 compatible object store with at least support for Signature Version 2 (http://docs.aws.amazon.com/AmazonS3/latest/dev/auth-request-sig-v2.html)

OX Engage – Components

  • Integrated Campaign Management Platform - where campaigns get created
  • Mail Injection Middleware - which decouples the OX Dovecot Pro IMAP server from the CMP
  • OX Dovecot Pro IMAP Server - fetches campaign templates and any user-specific variables provided by Customer and injects messages into the users IMAP stream

Download and Installation of OX Engage

Additional Packages

Please Note: OX Engage is only available for OX Dovecot Pro as part of the OX Monetization Program. Please contact Open-Xchange Sales for further information.

  • mail-injection-middleware - Decouples the OX Dovecot Pro IMAP server from the CMP [Patent "Ad hoc injection of IMAP objects" (US 9531785 B1) see United States Patent or Google Patents]

Installation on the server varies depending on the underlying distribution, details are as follows.

Download and Installation Mail Injection Middleware

Debian GNU/Linux 9.0

If not already done, add the following repositories to your Open-Xchange yum configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/ads/stable/mail-injection-middleware/DebianStretch /

and run

$ apt-get update
$ apt-get install mail-injection-middleware

Redhat Enterprise Linux 7

If not already done, add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mail-injection-middleware]
name=Open-Xchange-mail-injection-middleware
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/ads/stable/mail-injection-middleware/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update
$ yum install mail-injection-middleware

Prepare Cassandra

A Cassandra keyspace needs to be created where the MIM does create all necessary tables automatically then. Below example shows the CQL command to create a keyspace for development or basic testing purposes.

Important: You need to choose a strategy and replication factors depending on your physical Cassandra setup. In most cases this is probably 'NetworkTopologyStrategy' with replication factors >= 2 per data center. A proper replication configuration is crucial for mail injection decisions and the availability of mail contents.

CREATE KEYSPACE mim WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'};

Server Configuration

Before the MIM daemon can be started for the first time, it must be basically configured.

Note: Configuration files are not merged automatically via post-install scripts. Administrators need to take of comparing their configurations with newer default file versions.

Process and Java Options

Process limits (ulimits) like number of child processes and number of open files must be configured via systemd, similar as described here: http://oxpedia.org/wiki/index.php?title=AppSuite:ResourceLimits.

JVM options can be configured in /opt/mail-injection-middleware/conf/mail-injection-middleware.conf. The most important property is the max. heap size the JVM may acquire via the Xmx option.

Application Properties

The application itself gets configured in /opt/mail-injection-middleware/conf/application.properties. Most mandatory options are set to reasonable defaults. Others like Cassandra connection properties and S3 access must be set manually.

# Cassandra
# All possible properties can be found here:  https://docs.spring.io/spring-boot/docs/1.5.4.RELEASE/reference/html/common-application-properties.html. Search for prefix  "spring.data.cassandra".
spring.data.cassandra.keyspace-name=mim
spring.data.cassandra.contact-points=<cassandra-hosts>
spring.data.cassandra.port=9042
spring.data.cassandra.schema-action=CREATE_IF_NOT_EXISTS 

### Tenant Management ###
# One tenant has to be configured "defaultTenant = true" and in this one dataSource has to be "defaultDataSource = true".

app.tenantList[0].id = default
app.tenantList[0].name = Default Tenant
app.tenantList[0].defaultTenant = true (there has to be only one default tenant)
app.tenantList[0].keyspaceName = mim

app.tenantList[0].dataSources[0].id = default
app.tenantList[0].dataSources[0].type = ongage
app.tenantList[0].dataSources[0].defaultDataSource = true (there has to be only one default datasource)
app.tenantList[0].dataSources[0].secretKey = <secretKey>
app.tenantList[0].dataSources[0].metadataFilename = metadata.json
app.tenantList[0].dataSources[0].templateFilename = template.json
app.tenantList[0].dataSources[0].placeholderFilename = placeholders.json
app.tenantList[0].dataSources[0].deleteTemporaryImportFiles = true

app.tenantList[0].dataSources[0].awsConnectionInformation.authorizationType = rados
app.tenantList[0].dataSources[0].awsConnectionInformation.endpoint = <endpoint>
app.tenantList[0].dataSources[0].awsConnectionInformation.region = eu-west-1
app.tenantList[0].dataSources[0].awsConnectionInformation.accessKey = <accessKey>
app.tenantList[0].dataSources[0].awsConnectionInformation.secretKey = <secretKey>
app.tenantList[0].dataSources[0].awsConnectionInformation.signer = S3SignerType
app.tenantList[0].dataSources[0].awsConnectionInformation.bucket = <bucket>

Start Service

$ systemctl start mail-injection-middleware.service

The MIM starts logging to /var/log/mail-injection-middleware/mail-injection-middleware.log shortly after starting the service. Start-up was successful if no ERROR messages with Java stacktraces appear in the log and the INFO message "Started MIMApplication in XX.XXX seconds (JVM running for XX.XXX)" was printed.

Adding new tenants

Before configuring new tenants in application.properties an admin has to create the new keyspace and tables in it in advance. See script https://gitlab.open-xchange.com/advertising/mim/blob/develop/dataset_tables.cql