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

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.

Tenant Management

OX Dovecot Pro Compatibility

To ensure Dovecot compatibility there has to be at a tenant with the ID "default". This tenant is used for every Dovecot request automatically as Dovecot doesn't provide tenantId's via URL.

Tenant

Create new tenant

POST (url)/api/tenants/?createDB=true - This call will create a new keyspace and tables for the tenant in addition to the configuration data stored in keyspace "spring.data.cassandra.keyspace-name". In case createDB isn't set or set to false the keyspace and tables have to be present before the first usage of the tenant. 

{"id":"default",
 "name":"default",
 "keyspaceName":"mim_default",
 "configuration": {
   "secretKey":"<secretKey>"
 },
 "conversionPoints": [{
   "id":"injection",
   "type": "ongage",
   "eventType":"injected",
   "description": "Dovecot Injection Tracking",
   "connectionInformation": {
       "url": "<injectionUrl>"
   }
 },{
   "id":"reinjection",
   "type": "ongage",
   "eventType":"reinjected",
   "description": "Dovecot Re-Injection Tracking",
   "connectionInformation": {
       "url": "<reinjectionUrl>"
   }
 },{
   "id":"read",
   "type": "ongage",
   "eventType":"read",
   "description": "Dovecot Read Tracking",
   "connectionInformation": {
       "url": "<readUrl>"
   }
 },{
   "id":"expunged",
   "type": "ongage",
   "eventType":"expunged",
   "description": "Dovecot Expunged Tracking",
   "connectionInformation": {
       "url": "<expungedUrl>"
   }
 }],
 "dataSources": [{
   "id":"default",
   "type": "ongage",
   "defaultDataSource": true,
   "deleteTemporaryImportFiles":false,
   "awsConnectionInformation": {
     "authorizationType":"rados", 
     "accessKey":"<accessKey>",
     "secretKey":"<secretKey>",
     "endpoint":"<endpoint>",
     "bucket":"<bucket>"
     }
   }]}

Delete tenant

DELETE (url)/api/tenants/(tenantId)/ - Deletes tenant configuration data stored in keyspace "spring.data.cassandra.keyspace-name". The keyspace related to this tenant will NOT be deleted.

DataSources

DataSources are used as import-sources. In most cases there has to be only one DataSource per tenant - this has to be marked as default (defaultDataSource = true). The first DataSource will be created during tenant creation.

List DataSources

GET (url)/api/tenants/(tenantId)/dataSources

Change DataSources

PUT (url)/api/tenants/(tenantId)/dataSources - Use the result of the list call, modify accordingly and provide the whole new list.

Retrieved from "https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Monetization_Engage&oldid=24735"