AppSuite:OX Engage

Introduction

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 an SMTP server or protocol.

Information that is stored in these IMAP objects can include advertising, promotions, service alerts or any other conceivable content of a regular email. 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 the objects to be injected, the respective time schedule and target audience, as well as the position of the message in the user’s inbox, are dependent on a configurable object- and/or user profiles and other targeting parameters.

Components

  • Integrated Campaign Management Platform (CMP) to create and schedule campaigns through a user interface.
  • OX Mail Injection Middleware (MIM) to decouple the OX Dovecot Pro IMAP server from the CMP.
  • OX Dovecot Pro IMAP Server (to be obtained separately) to fetch campaign templates and any user-specific variables provided by the Customer and to inject messages into the user’s IMAP stream.
  • OX Monetization Database (MDB), only for OX Managed customers, to map userID to email address.

Please see the Product Guide for more information about OX Engage v1.1.0.

Requirements

Please Note: OX Engage is only available for OX Dovecot Pro. Please contact the OX Monetization Team for further information.

The following is required:

  • 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 Dovecot Pro as an underlying IMAP server

Download and Installation

Decouples the OX Dovecot Pro IMAP server from the CMP

  • mail-injection-middleware

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

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

Cassandra

A Cassandra keyspace needs to be created where the MIM does create all necessary tables automatically then. The 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.

Please 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 a number of child processes and the 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's 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.

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>",
   "hashedEmailAddresses": true/false
 },
 "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_Engage&oldid=25381"